---
id: setuptools-git-versioning
version: "3.1.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# setuptools-git-versioning — Use git repo data for building a version number according to PEP-440

License: permissive · Maintenance: active · Downloads: 1.6M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

git-based version numbering, automatic pep 440 versioning, setuptools git versioning, version from git tags, dynamic package versioning, build-automation, version-management

[View on SkillFed](https://skillfed.io/packages/setuptools-git-versioning) · [View on PyPI](https://pypi.org/project/setuptools-git-versioning/)