calver-scm 1.7.0

calver-scm is a setuptools-scm plugin that generates CalVer version strings directly from your Git tags and commit history. No __version__ files to maintain, no manual bumping; just tag and go.

Versions look like this:

2026.4.0          -> clean tag, April 2026, patch 0
2026.4.1.dev3     -> 3 commits after that tag, still April, patch incremented
2026.5.0.dev3     -> 3 commits after an old tag, month rolled over, patch reset
2026.4.15.0       -> day mode: clean tag on the 15th
2026.4.15.1.dev2  -> day mode: 2 commits after a tag on the same day
2026.4.0.dev12    -> no tag yet, 12 commits in
0.2026.4.0        -> same release line, but marked unstable/pre-1.0

Installation

pip install calver-scm

Then wire it into your pyproject.toml. Pick the setup that matches your build backend:

Quickstart (hatch-vcs, recommended)

If you use Hatchling, this is the shortest working setup:

[build-system]
requires = ["hatchling", "hatch-vcs", "calver-scm"]
build-backend = "hatchling.build"

[project]
dynamic = ["version"]

[tool.hatch.version]
source = "vcs"

[tool.hatch.version.raw-options]
version_scheme = "calver-scm"
local_scheme   = "dirty-tag"

dynamic = ["version"] is required so Hatch knows the version is resolved from VCS at build time.

With setuptools

[build-system]
requires = ["setuptools", "setuptools-scm", "calver-scm"]
build-backend = "setuptools.build_meta"

[project]
dynamic = ["version"]

[tool.setuptools_scm]
version_scheme = "calver-scm"
local_scheme   = "dirty-tag"

dynamic = ["version"] is required when using PEP 621 metadata in pyproject.toml.

hatch-vcs extras (optional)

The quickstart config above is enough for most projects. If you want a runtime __version__ file, hatch-vcs can write one during builds:

[tool.hatch.build.hooks.vcs]
version-file = "src/your_package/_version.py"

Then in your __init__.py:

from ._version import __version__

That's it. Your project will now version itself automatically on every build.

CI note

This plugin derives versions from Git history and tags. In CI, make sure your checkout includes tags and enough history to resolve the latest version tag.

How versions are generated

The generated version shape is config-driven. In general, it looks like:

[0.]<DATE_BASE>.PATCH[.devN][+local]

• <DATE_BASE> comes from mode/scheme (for example YYYY, YYYY.MM, YYYY.WW, or YYYY.MM.DD).
• 0. is included only when stable = false.
• .devN appears for non-tag builds (and in no-tag fallback when fallback = "dev").
• +local (including +dirty) depends on your setuptools-scm local_scheme.

If stable = false, calver-scm prefixes the generated public version with 0. to indicate an explicitly unstable release line:

2026.4.0      -> stable output (default)
0.2026.4.0    -> unstable output
0.2026.4.1.dev3

The patch segment increments automatically from your last tag within the current period, and resets to 0 whenever the month (or day, in day mode) rolls over.

The date segment is derived from the build/runtime date, not from commit timestamps.

Pre-release, post-release, and local tags

If your Git tag carries any PEP 440 suffix, calver-scm preserves it in the generated version and normalises it to its PEP 440 canonical form.

Pre-release suffixes (a, b, rc)

Tag any of the recognised PEP 440 aliases and it is normalised automatically:

v2026.4.0a1     -> 2026.4.0a1
v2026.4.0beta2  -> 2026.4.0b2
v2026.4.0pre1   -> 2026.4.0rc1
v2026.4.0rc1    -> 2026.4.0rc1

Post-release suffixes (post)

v2026.4.0-r1     -> 2026.4.0.post1
v2026.4.0.rev2   -> 2026.4.0.post2
v2026.4.0.post-3 -> 2026.4.0.post3
v2026.4.0.post3  -> 2026.4.0.post3

Dev suffixes (dev)

v2026.4.0.dev    -> 2026.4.0.dev0
v2026.4.0.dev-4  -> 2026.4.0.dev4
v2026.4.0.dev4   -> 2026.4.0.dev4

Local version segment (+)

A +local segment on a tag is preserved as-is. PEP 440 normalises underscores to dots within local identifiers:

v2026.4.0+abc            -> 2026.4.0+abc
v2026.4.0+linux.x86_64   -> 2026.4.0+linux.x86.64

Note: The +local segment on a tag is distinct from the +dirty suffix that setuptools-scm appends for uncommitted working-tree changes. See Local scheme for how to control that behaviour.

Combining suffixes

All segments can be combined and are each normalised independently:

v2026.4.0rc1.post2.dev3+local -> 2026.4.0rc1.post2.dev3+local

Configuration

Add a [tool.calver-scm] section to pyproject.toml to customise behaviour. All fields are optional, and the defaults shown below are sensible for most projects.

[tool.calver-scm]
mode       = "month"   # "year" | "month" | "week" | "day"
scheme     = "YYYY.MM" # optional token scheme; defaults from mode
patch      = true      # auto-increment patch within a period
stable     = true      # emit normal tags, or prefix versions with 0. when false
no_dev     = false     # suppress .devN suffix on non-exact versions
fallback   = "dev"     # "dev" | "date" (when no tag exists)
tag_prefix = "v"       # prefix stripped when reading tags
timezone   = "UTC"     # "UTC" (default), "local", or IANA tz name

If scheme is omitted, calver-scm uses sensible defaults:

• mode = "year" -> YYYY
• mode = "month" -> YYYY.MM
• mode = "week" -> YYYY.WW
• mode = "day" -> YYYY.MM.DD

Supported scheme tokens follow CalVer terminology: YYYY, YY, MM, WW, DD.

Week tokens (WW) cannot be combined with month/day tokens.

mode

Controls the time granularity of the version base.

• "year": base is YYYY (e.g. 2026)
• "month": base is YYYY.MM (e.g. 2026.4)
• "week": base is YYYY.WW (e.g. 2026.16)
• "day": base is YYYY.MM.DD (e.g. 2026.4.15)

# Year mode: annual cadence
[tool.calver-scm]
mode = "year"
# -> 2026.0, 2026.1.dev3 ...

# Month mode (default): good for most projects
[tool.calver-scm]
mode = "month"
# -> 2026.4.0, 2026.4.1.dev3, 2026.5.0.dev1 ...

# Week mode: weekly cadence
[tool.calver-scm]
mode = "week"
# -> 2026.16.0, 2026.16.1.dev2 ...

# Day mode: useful for projects that release frequently
[tool.calver-scm]
mode = "day"
# -> 2026.4.15.0, 2026.4.15.1.dev2, 2026.4.16.0.dev1 ...

scheme

Defines the date portion explicitly using CalVer tokens.

# Explicitly match the default month style
[tool.calver-scm]
scheme = "YYYY.MM"

# Short year + month
[tool.calver-scm]
scheme = "YY.MM"
# -> 26.4.0, 26.4.1.dev3

# Year + ISO week (week schemes are month/day-exclusive)
[tool.calver-scm]
scheme = "YYYY.WW"
# -> 2026.16.0, 2026.16.1.dev2

patch

When true, the patch number increments from the last tag within the same period. When false, patch is always 0 and only the .devN distance distinguishes pre-release builds.

# patch = true (default): each build within a period gets a unique patch number
[tool.calver-scm]
patch = true
# tag v2026.4.2, then 3 commits later -> 2026.4.3.dev3

# patch = false: patch stays 0, only devN changes
[tool.calver-scm]
patch = false
# tag v2026.4.2, then 3 commits later -> 2026.4.0.dev3

stable

Controls whether generated public versions are emitted as stable releases or explicitly marked as unstable with a leading 0. prefix.

# stable = true (default): emit standard CalVer versions
[tool.calver-scm]
stable = true
# tag v2026.4.2, then 3 commits later -> 2026.4.3.dev3

# stable = false: prefix generated output with 0.
[tool.calver-scm]
stable = false
# tag v2026.4.2, then 3 commits later -> 0.2026.4.3.dev3

While stable = false, both v0.2026.4.3 and legacy unprefixed tags like v2026.4.3 are accepted as parseable historical bases to ease migration. When you switch to stable = true, tags that still carry the unstable 0. prefix are treated as incompatible and the version scheme falls back until you create the first stable tag.

For a go-live cutover, the recommended flow is:

1. develop and pre-release with stable = false
2. flip to stable = true on the release commit
3. create the first stable tag, for example v2026.4.0

That keeps the unstable 0. tag line distinct from the stable release line and avoids silently reinterpreting old unstable tags as stable ones.

no_dev

When true, suppresses the .devN suffix on generated versions, emitting a clean {base}.{patch} version even when commits exist after the latest tag or when falling back in an untagged repository.

# no_dev = false (default): normal development versions with distance suffix
[tool.calver-scm]
no_dev = false
# tag v2026.4.2, then 3 commits later -> 2026.4.3.dev3

# no_dev = true: suppress dev suffix for release workflows
[tool.calver-scm]
no_dev = true
# tag v2026.4.2, then 3 commits later -> 2026.4.3

This is especially useful in release CI workflows that compute the clean target release version, create the tag, and publish the release in one pass without requiring a separate bumping step.

Note: no_dev only suppresses the public .devN version segment. Setuptools-scm's local_scheme (such as the default node-and-date) can still append a +g... local segment on untagged commits. Pair no_dev = true / CALVER_SCM_NO_DEV=true with a distance-insensitive local scheme like dirty-tag or no-local-version (or CI overrides like no-local-version-strict) to ensure a clean version string.

fallback

Controls what happens when no tag exists yet in the repository.

• "dev": emits YYYY.MM.0.devN where N is the total commit count (default)
• "date": emits YYYY.MM.0 with no dev segment, useful for initial releases

# fallback = "dev" (default): makes it clear this is a pre-release build
[tool.calver-scm]
fallback = "dev"
# 12 commits, no tag yet -> 2026.4.0.dev12

# fallback = "date": emits a clean version even before the first tag
[tool.calver-scm]
fallback = "date"
# 12 commits, no tag yet -> 2026.4.0

tag_prefix

The string that must prefix a tag for it to be recognised as a CalVer tag. Set to "" if your tags have no prefix.

# tag_prefix = "v" (default): tags like v2026.4.0
[tool.calver-scm]
tag_prefix = "v"

# No prefix: tags like 2026.4.0
[tool.calver-scm]
tag_prefix = ""

# Custom prefix: tags like release-2026.4.0
[tool.calver-scm]
tag_prefix = "release-"

timezone

Controls which timezone is used to compute the date segment.

• "UTC": default; deterministic across environments
• "local": machine local timezone
• Any valid IANA timezone, e.g. "Europe/London", "America/New_York"

# Default, recommended for CI/reproducibility
[tool.calver-scm]
timezone = "UTC"

# Use host local timezone
[tool.calver-scm]
timezone = "local"

# Explicit IANA timezone
[tool.calver-scm]
timezone = "Pacific/Auckland"

Environment variable overrides

Every option can be overridden at build time without touching pyproject.toml, which is handy for CI pipelines.

Environment variables take precedence over pyproject.toml.

Local scheme

calver-scm controls the public version segment only. The +dirty suffix is handled separately by setuptools-scm's built-in local schemes. Pick whichever suits you:

[tool.setuptools_scm]
version_scheme = "calver-scm"
local_scheme   = "dirty-tag"         # +dirty on uncommitted changes (recommended)
# local_scheme = "no-local-version"  # suppress the local segment entirely
# local_scheme = "node-and-date"     # +g1a2b3c4.d20260415 (setuptools-scm default)

Command line

An optional command line reports the version your project's build would produce, without building anything.

pip install 'calver-scm[cli]'

calver-scm version                  # 2026.4.3.dev3+g1a2b3c4
calver-scm version --root ./backend # a project in a subdirectory
calver-scm version --json           # {"version": "2026.4.3.dev3+g1a2b3c4"}

version reads the project's own [tool.setuptools_scm] or Hatch-VCS [tool.hatch.version] settings and asks setuptools-scm for the result, so it includes your local_scheme and honours CALVER_SCM_* overrides. It fails if the project does not use version_scheme = "calver-scm".

calver-scm validate 2026.4.2                 # valid: 2026.4.2
calver-scm validate v2026.4.2 --tag          # check a Git tag, including its prefix
calver-scm validate 2026.13.1 --json         # {"valid": false, "input": ..., "errors": [...]}

validate checks that a version is valid PEP 440 and fits your configured scheme: the number of date components, calendar ranges (month 1-12, real days of the month, week 1-53), the stable setting's 0. prefix and, with --tag, the tag_prefix. Pre-release, post-release, dev and local suffixes are accepted. It reads [tool.calver-scm] (and CALVER_SCM_* overrides) from --root but needs no Git checkout. Week 53 is accepted in any year because YYYY.WW takes its year from the calendar date, not the ISO week-year.

Explaining a version

calver-scm explain

Shows how the build version was derived: the tag, commit distance and dirty flag that setuptools-scm supplied, the date and timezone used, which branch of the algorithm ran (exact_tag, patch_incremented, patch_reset, no_tag_fallback or incompatible_tag_fallback), the effective configuration, and any CALVER_SCM_* overrides in force. It separates the public_version that calver-scm produced from the local_segment that your local_scheme appended afterwards. It runs the same code path as a real build, and it never prints absolute paths.

The reason is one of:

Diagnosing problems

calver-scm doctor

Runs independent checks and carries on past failures: whether the build configuration uses the calver-scm scheme, whether [tool.calver-scm] and the environment overrides are valid, whether Git is available, whether the version resolves, and warnings for shallow clones, a missing compatible tag, and no_dev combined with a local segment. Each finding has a code, a severity (ok, info, warning or error) and, where useful, a suggested fix. Warnings never fail the command; errors do. Error details can include file paths.

Planning the next release tag

git tag "$(calver-scm next-tag)"     # prints e.g. v2026.4.3

next-tag is read-only: it proposes a tag and never creates or pushes one. It looks at every local tag, not only those reachable from HEAD, so a number used on another branch is not reused. Pre-releases and dev releases occupy no number, post-releases do, and tags that do not fit the scheme are ignored. It honours tag_prefix, stable and the timezone. With patch = false it refuses a second release in the same period. It also refuses a shallow clone, because the tag list cannot be trusted. Tags that exist only on the remote and have not been fetched cannot be seen, so run git fetch --tags first.

The reason is one of:

How next-tag differs from version

calver-scm version describes the commit you are on; next-tag plans a release. They agree in a simple, linear history, so CALVER_SCM_NO_DEV=true calver-scm version and calver-scm next-tag give the same number there. They are not the same thing:

Use version to see what a build will be called, and next-tag to decide what to tag.

Output formats

Pick how results are written with the global --format option, before or after the command:

calver-scm version                    # rich in a terminal
calver-scm version | cat              # plain: 2026.4.3.dev3+g1a2b3c4
calver-scm --format json version

Piping or redirecting therefore always gives plain text without needing a flag. Plain is the stable format for scripts: one value per line, or key: value lines, with no decoration. Run calver-scm --help, or calver-scm COMMAND --help, for the options, worked examples and exit codes of each command. calver-scm --version prints the installed calver-scm release.

Exit codes

Errors and invalid configuration

Errors are always plain text on stderr, whatever the format, and leave stdout empty. If [tool.calver-scm], a CALVER_SCM_* variable or pyproject.toml itself is invalid, every command stops with error: Invalid config: … and exit code 2. doctor is the exception: it reports the problem as an error check, carries on with the other checks, and exits 1. The build behaves the same way in spirit: setuptools-scm raises a RuntimeError with the same message, so the build fails instead of producing a wrong version.

validate is also an exception to "errors go to stderr": an invalid input is its answer, so the verdict goes to stdout, and with --json it stays parseable.

JSON output

--json (or --format json) prints a single JSON object on one line. A missing value is always null, never an omitted key. New keys may be added in a future release, so ignore keys you do not know. The reason, severity, status and error code values below are stable identifiers; the wording of messages and summaries is not.

// version
{"version": "2026.4.3.dev3+g1a2b3c4"}

// validate (exit code 1 when "valid" is false)
{"valid": false, "input": "2026.13.1",
 "errors": [{"code": "invalid_month", "message": "Month must be between 1 and 12, got 13"}]}

// next-tag
{"tag": "v2026.4.3", "version": "2026.4.3", "patch": 3,
 "reason": "next_patch", "latest_tag": "v2026.4.2"}   // latest_tag is null for a new period

// explain
{"version": "2026.4.3.dev3+g1a2b3c4", "public_version": "2026.4.3.dev3",
 "local_segment": "g1a2b3c4",                        // null when the local_scheme adds nothing
 "reason": "patch_incremented",
 "scm": {"tag": "2026.4.2", "distance": 3, "dirty": false},
 "calculation": {"date": "2026-04-15", "timezone": "UTC", "base": "2026.4",
                 "tag_base": "2026.4", "tag_patch": 2, "patch": 3},
 "config": {"mode": "month", "scheme": "YYYY.MM", "patch": true, "stable": true,
            "no_dev": false, "fallback": "dev", "tag_prefix": "v"},
 "env_overrides": {"CALVER_SCM_NO_DEV": "true"}}      // {} when none are set

// doctor
{"status": "warning",                                // ok, warning or error
 "checks": [{"code": "no_compatible_tag", "severity": "warning",
             "summary": "No tag fits the configured CalVer scheme",
             "detail": "The fallback applied; the tag seen was '0.0'.",
             "remediation": "Tag a release, for example v2026.4.0, …"}]}

validate error codes

doctor check codes

Without the cli extra the calver-scm command still exists but only prints how to install it.

Requirements

• Python >= 3.11
• setuptools-scm >= 10.0.5
• For the command line: the cli extra (installs Cyclopts, which also brings in Rich)

License

MIT