How to add dynamic versioning to uv projects

Dynamic versioning generates version numbers from Git tags instead of requiring manual updates to a static version string in pyproject.toml. The release workflow becomes a single git tag command: the build backend reads the tag, and the wheel and source distribution filenames pick up the matching version automatically.

This guide uses uv-dynamic-versioning, a hatchling plugin that ships a sensible default configuration for uv projects.

Prerequisites

• A Git repository for your Python project with at least one commit
• uv installed on your system
• A src/your_package/ layout (the default for uv init --package)

Configure the build system

Update pyproject.toml to use uv-dynamic-versioning as a build backend dependency:

[build-system]
requires = ["hatchling", "uv-dynamic-versioning"]
build-backend = "hatchling.build"

Set the version source

Mark the version field as dynamic and point hatchling at uv-dynamic-versioning:

[project]
name = "your-project"
dynamic = ["version"]  # Remove any static version = "..." line

[tool.hatch.version]
source = "uv-dynamic-versioning"

Create a Git tag

Tag a commit following the default pattern (a v prefix followed by a semantic version):

$ git tag v0.1.0

Build and verify

$ uv build

The built distribution’s filename includes the version derived from the tag, for example your_project-0.1.0-py3-none-any.whl.

Understand versions between tags

When the working tree is tagged exactly, the version is clean (0.1.0). When you build from a commit past the most recent tag, uv-dynamic-versioning appends a PEP 440 post-release and dev segment plus the commit hash as a local identifier:

your_project-0.1.0.post1.dev0+91cc190-py3-none-any.whl

The post1 counts commits since the tag and +91cc190 is the short commit hash. These development versions sort higher than the last release but lower than the next tagged release, so uv pip install . on a feature branch installs a version that supersedes 0.1.0 without claiming to be 0.2.0. PyPI rejects local version identifiers (anything after +), so only clean tagged builds can be uploaded.

Choose a version style and tag pattern

uv-dynamic-versioning computes versions with dunamai, the engine shared by several VCS-versioning tools. Configure its output under [tool.uv-dynamic-versioning]:

[tool.uv-dynamic-versioning]
style = "pep440"        # also "semver" or "pvp"
pattern = "default"     # "default" requires a "v" prefix; "default-unprefixed" drops it

• style selects the version scheme: pep440 (the default), semver, or pvp. The pep440 default produces 0.1.0.post1.dev0+91cc190. Wheel and sdist filenames are normalized to PEP 440 regardless, so keep pep440 unless another tool reads the raw version string.
• pattern decides which tags count as releases. default matches v1.2.3; default-unprefixed matches 1.2.3.
• The commit hash carries no prefix by default. Set commit-prefix = "g" for the git describe-style +g91cc190.

Fetch full history in CI

CI runners and release automation default to shallow clones, which strips the Git tags and history that uv-dynamic-versioning needs. Two common fixes:

GitHub Actions: tell actions/checkout to fetch the full history and tags.

- uses: actions/checkout@v5
  with:
    fetch-depth: 0
    fetch-tags: true

Dependabot and other shallow clones you cannot control: define a fallback so the build still succeeds when tags are missing.

[tool.uv-dynamic-versioning]
fallback-version = "0.0.0"

Use the fallback as a safety net, not as a substitute for a full checkout. Published releases should always build from a real tag.

Expose the version at runtime

To make the version accessible within the package:

# src/your_package/__init__.py
import importlib.metadata

try:
    __version__ = importlib.metadata.version(__name__)
except importlib.metadata.PackageNotFoundError:
    __version__ = "0.0.0"  # Fallback for development mode

This reads the version from installed package metadata, so it stays in sync with the Git tag without duplicating the value. The PackageNotFoundError branch only fires when the package is imported from a source tree that was never installed, for example when running tests directly against src/.

Release a new version

With dynamic versioning in place, cutting a release is two commands:

$ git tag v0.2.0
$ git push origin v0.2.0

Then trigger a publish. Pair this with trusted publishing to PyPI so the same tag that sets the version also triggers the release workflow.

Frequently asked questions

Do I still need to edit pyproject.toml on every release?

No. The whole point of dynamic versioning is that version is no longer a static string. The only file that changes on a release is the Git tag.

Should I use this or uv’s uv version command?

They solve different problems. uv version --bump patch (also major and minor) edits the static version string in pyproject.toml, so the file stays the source of truth and the tag is created afterward. uv-dynamic-versioning inverts that: the Git tag is the version, and there is no string to bump or forget. Reach for uv version when you want a committed version field and a manual release step; reach for uv-dynamic-versioning when you want the tag to drive the version with no edits.

One trade-off comes with the switch: once version is dynamic, uv version stops working and reports We cannot get or set dynamic project versions. Reading dynamic versions through uv version is tracked in astral-sh/uv#14137.

How is uv-dynamic-versioning different from setuptools-scm or hatch-vcs?

All three read the version from Git. setuptools-scm targets setuptools, hatch-vcs targets hatchling, and uv-dynamic-versioning is a lighter hatchling plugin with defaults tuned for uv projects. For a new uv project, uv-dynamic-versioning is the shortest path. Existing hatch-vcs setups work fine as-is.

Why is my CI build failing with “could not find a tag”?

The runner did a shallow clone. Set fetch-depth: 0 and fetch-tags: true on actions/checkout, or configure a fallback-version for environments you cannot control.

Related

• uv: A Complete Guide covers what uv does, how fast it is, the core workflows, and recent releases.
• uv-dynamic-versioning on GitHub
• pyproject.toml reference covers project metadata fields including dynamic
• What is a build backend? explains how hatchling and other backends work
• Why does uv use hatch as a backend? covers the default build backend for uv projects
• How to publish to PyPI with trusted publishing pairs well with tag-driven releases
• uv reference documents the uv build and uv publish commands