calver-scm 1.4.0

Automatic, date-based versioning for Python projects, powered by your Git history.

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.04.0          -> clean tag, April 2026, patch 0
2026.04.1.dev3     -> 3 commits after that tag, still April, patch incremented
2026.05.0.dev3     -> 3 commits after an old tag, month rolled over, patch reset
2026.04.15.0       -> day mode: clean tag on the 15th
2026.04.15.1.dev2  -> day mode: 2 commits after a tag on the same day
2026.04.0.dev12    -> no tag yet, 12 commits in
0.2026.04.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.04.0      -> stable output (default)
0.2026.04.0    -> unstable output
0.2026.04.1.dev3

Situation	Example
Clean tag, month mode	2026.04.0
Commits after tag, same month	2026.04.1.dev3
Commits after tag, previous month's tag	2026.05.0.dev3
Clean tag, day mode	2026.04.15.0
Dirty working tree	2026.04.0+dirty
No tag yet	2026.04.0.dev12

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:

Tag suffix	Canonical output
alpha / a	a
beta / b	b
preview / pre / c / rc	rc

v2026.04.0a1     -> 2026.04.0a1
v2026.04.0beta2  -> 2026.04.0b2
v2026.04.0pre1   -> 2026.04.0rc1
v2026.04.0rc1    -> 2026.04.0rc1

Post-release suffixes (post)

Tag suffix	Canonical output
-rN / revN	postN
post-N / postN	postN

v2026.04.0-r1     -> 2026.04.0.post1
v2026.04.0.rev2   -> 2026.04.0.post2
v2026.04.0.post-3 -> 2026.04.0.post3
v2026.04.0.post3  -> 2026.04.0.post3

Dev suffixes (dev)

Tag suffix	Canonical output
dev (bare)	dev0
dev-N / devN	devN

v2026.04.0.dev    -> 2026.04.0.dev0
v2026.04.0.dev-4  -> 2026.04.0.dev4
v2026.04.0.dev4   -> 2026.04.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.04.0+abc            -> 2026.04.0+abc
v2026.04.0+linux.x86_64   -> 2026.04.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.04.0rc1.post2.dev3+local -> 2026.04.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.0M" # 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
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.0M
• mode = "week" -> YYYY.0W
• mode = "day" -> YYYY.0M.0D

Supported scheme tokens follow CalVer terminology: YYYY, YY, 0Y, MM, 0M, WW, 0W, DD, 0D.

Week tokens (WW, 0W) 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.04)
• "week": base is YYYY.WW (e.g. 2026.16)
• "day": base is YYYY.MM.DD (e.g. 2026.04.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.04.0, 2026.04.1.dev3, 2026.05.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.04.15.0, 2026.04.15.1.dev2, 2026.04.16.0.dev1 ...

scheme

Defines the date portion explicitly using CalVer tokens.

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

# Short year + month
[tool.calver-scm]
scheme = "YY.0M"
# -> 26.04.0, 26.04.1.dev3

# Year + ISO week (week schemes are month/day-exclusive)
[tool.calver-scm]
scheme = "YYYY.0W"
# -> 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.04.2, then 3 commits later -> 2026.04.3.dev3

# patch = false: patch stays 0, only devN changes
[tool.calver-scm]
patch = false
# tag v2026.04.2, then 3 commits later -> 2026.04.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.04.2, then 3 commits later -> 2026.04.3.dev3

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

While stable = false, both v0.2026.04.3 and legacy unprefixed tags like v2026.04.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.04.0

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

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.04.0.dev12

# fallback = "date": emits a clean version even before the first tag
[tool.calver-scm]
fallback = "date"
# 12 commits, no tag yet -> 2026.04.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.04.0
[tool.calver-scm]
tag_prefix = "v"

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

# Custom prefix: tags like release-2026.04.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.

Variable	Equivalent option
CALVER_SCM_MODE	mode
CALVER_SCM_SCHEME	scheme
CALVER_SCM_PATCH	patch (true / false)
CALVER_SCM_STABLE	stable (true / false)
CALVER_SCM_FALLBACK	fallback
CALVER_SCM_TAG_PREFIX	tag_prefix
CALVER_SCM_TIMEZONE	timezone

Environment variables take precedence over pyproject.toml.

Migration note: Environment variable names were renamed from SCM_CALVER_* to CALVER_SCM_*.

• SCM_CALVER_MODE -> CALVER_SCM_MODE
• SCM_CALVER_SCHEME -> CALVER_SCM_SCHEME
• SCM_CALVER_PATCH -> CALVER_SCM_PATCH
• SCM_CALVER_STABLE -> CALVER_SCM_STABLE
• SCM_CALVER_FALLBACK -> CALVER_SCM_FALLBACK
• SCM_CALVER_TAG_PREFIX -> CALVER_SCM_TAG_PREFIX
• SCM_CALVER_TIMEZONE -> CALVER_SCM_TIMEZONE

---

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)

---

Requirements

• Python >= 3.10
• setuptools-scm >= 10.0.5
• tomli >= 2.4.1 on Python < 3.11 (the stdlib tomllib is used on 3.11+)

---

License

MIT