How to add dynamic versioning to uv projects

This guide shows you how to implement Git based dynamic versioning in your Python projects using uv-dynamic-versioning. This approach automatically generates version numbers from Git tags, eliminating the need to manually update version strings in your code.

Prerequisites

• A Git repository for your Python project
• uv installed on your system

Setup uv-dynamic-versioning

First, configure your project’s build system to use uv-dynamic-versioning by updating your pyproject.toml:

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

Configure Version Source

1. Add a version source configuration in your pyproject.toml:

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

2. Change your project metadata to use dynamic versioning:

[project]
name = "your-project"
dynamic = ["version"]  # Remove static version and add this line

Create a Git Tag

Create a Git tag that follows the versioning pattern (by default, a “v” prefix followed by a semantic version):

git tag v0.1.0

Build Your Project

Build your project to verify the dynamic versioning:

uv build

Adding a Fallback Version

To provide a fallback version for environments without version control information (like when Dependabot runs):

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

Exposing the Version in Your Package

To make the version accessible within your package:

# 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

Learn More

• uv-dynamic-versioning on GitHub