setuptools-scm

setuptools-scm is the blessed way to manage your Python package versions using your source control metadata instead of hardcoded version strings. It extracts the version from Git or Mercurial tags at build time and integrates directly with setuptools and modern PEP 517 build backends.

Beyond versioning, it can determine the set of files under version control for inclusion in your distribution, and it provides configurable schemes for how tagged, development, and dirty working-tree versions are formatted — keeping your published version numbers accurate and reproducible.

What You Get

• Automatic package versioning from Git or Mercurial tags at build time
• Configurable version and local-version schemes for dev, dirty, and tagged states
• Automatic discovery of version-controlled files for inclusion in distributions

Common Use Cases

• Eliminating hardcoded version strings and manual version bumps
• Producing reproducible, PEP 440-compliant versions in CI/CD release pipelines
• Writing a generated _version.py file for runtime access to the package version

Under The Hood

Architecture

setuptools-scm is a monorepo pairing the setuptools plugin (setuptools-scm/) with an extracted, backend-agnostic core (vcs-versioning/). At build time it hooks setuptools entry points, queries Git/Mercurial for the nearest tag and distance, and feeds that through pluggable version-scheme and local-scheme functions to produce a PEP 440 string, optionally emitting a _version.py.

Tech Stack

Pure Python packaged with modern tooling — pyproject.toml, a uv workspace, uv.lock, and mkdocs for docs. It integrates with setuptools and PEP 517 build frontends and shells out to the git and hg binaries to read repository metadata.

Code Quality

The project maintains an extensive pytest suite (testing_scm and testing_vcs) run under tox across Python versions, plus CONTRIBUTING, TESTING, and RELEASE_SYSTEM guides. As a foundational packaging tool depended on across the ecosystem, it holds a high bar for backward compatibility and test coverage.

API Design

Most users configure it declaratively in pyproject.toml with a few lines and never touch code, which is the ideal experience for build tooling. Advanced version-scheme customization and the CLI (python -m setuptools_scm) add power for complex projects, at the cost of a configuration surface that rewards reading the docs.