setuptools-git-versioning

What it is and what it does

setuptools-git-versioning is a setuptools plugin that derives your package's version number directly from your git repository state at build time. Instead of hardcoding a version string in setup.py or pyproject.toml, it reads git tags, commit hashes, and dirty status to generate a PEP 440-compliant version automatically. This eliminates the need to manually bump version strings before releases and keeps your version source-of-truth in git tags.

The plugin integrates into the build process via setuptools' build backend or scikit-build-core, supporting both pyproject.toml and setup.py configuration. It offers tag-based, file-based, and callback-based versioning schemas with customizable templates for tagged, development, and dirty-state versions. Configuration is minimal—typically just enabling the plugin and marking version as dynamic—and it requires only git v2 and setuptools to be available.

Use it for:

• Automatically version releases by creating git tags without editing version strings in source files.
• Generate development versions with commit hashes for pre-release builds and CI/CD pipelines.
• Mark builds from uncommitted changes with a 'dirty' suffix to distinguish development snapshots from clean releases.
• Maintain a single source of truth for versioning in git history rather than scattered version strings across the codebase.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Automatically generates PEP 440-compliant version numbers for Python packages based on git repository state (tags, commits, dirty status) during the build process.

Yes, if you use setuptools or scikit-build-core and want to eliminate manual version management. The package is actively maintained, has no known vulnerabilities, low install friction, and a permissive license. The main constraint is that it requires a git repository and Git v2; if your build process does not have git available or you use a different build backend (Poetry, etc.), it will not work.

Install

setuptools-git-versioning on PyPI

pip install setuptools-git-versioning

uv add setuptools-git-versioning

poetry add setuptools-git-versioning

Installing setuptools-git-versioning

Before you install

Low friction installation with a pure-wheel distribution. Actively maintained as of 2026-05-15 with recent commits. Three lightweight runtime dependencies (packaging, setuptools, tomli) that are commonly already present in build environments.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects with minimal restrictions.

Quickstart

# In pyproject.toml:
[build-system]
requires = ["setuptools>=41", "wheel", "setuptools-git-versioning>=3.0,<4"]
build-backend = "setuptools.build_meta"

[tool.setuptools-git-versioning]
enabled = true

[project]
dynamic = ["version"]

# Then run:
$ setuptools-git-versioning
# Output: 0.0.1 (or version based on git tag)

Requires a Git repository and Git v2 to be present; only works with setuptools or scikit-build-core build backends, not Poetry or others.

Verify before relying

• Whether the package handles shallow clones or sparse checkouts correctly.
• Performance impact when called repeatedly during complex multi-stage builds.
• Compatibility with monorepo setups where multiple packages share a single git root.

Package facts

Evidence: setuptools_git_versioning-3.1.0-py3-none-any.whl

Keywords: setuptools, git, versioning, pep-440

Tags

More Build Tools packages