Repolode
Submit
pypa

pypa/setuptools-scm

A Python tool that derives package version numbers from Git or Mercurial tags, integrating with setuptools.

View on GitHubWebsite
Stars
954
Forks
251
Open issues
26
Last commit
2 days ago

What is it?

setuptools-scm extracts Python package versions from the version control system metadata of a project, typically Git or Mercurial tags. Instead of maintaining a version string by hand in setup files, the version is computed at build time from the most recent tag and the commit state, so releases and development builds stay consistent with the repository history.

The package plugs into setuptools and can also be used on its own through its own tooling. The repository is a monorepo holding two projects: setuptools-scm itself, and vcs-versioning, a core VCS versioning library that can be used independently of setuptools.

The repository uses uv for dependency management, with commands for installing all packages and dependency groups, running the pytest suites for each project, and building the shared mkdocs documentation.

Key features

  • 01Derives version numbers from Git or Mercurial tags at build time.
  • 02Integrates with setuptools for Python package builds.
  • 03Ships vcs-versioning as a standalone library usable without setuptools.
  • 04Includes test suites run with pytest and documentation built with mkdocs.

Use cases

  • Keeping Python package versions tied to Git tags without editing version strings by hand.
  • Versioning a Python project that is tracked in Git or Mercurial.
  • Reusing VCS-based version detection in tooling that does not use setuptools.

Quick start

  1. 1

    Install all packages and dependency groups with uv

    uv sync --all-packages --all-groups
  2. 2

    Run the test suite

    uv run pytest -n12

Topics

#python#packaging#version-control#setuptools#git#versioning#metadata

FAQ

What is setuptools-scm?
A Python tool that derives package version numbers from Git or Mercurial tags, integrating with setuptools. setuptools-scm extracts Python package versions from the version control system metadata of a project, typically Git or Mercurial tags. Instead of maintaining a version string by hand in setup files, the version is computed at build time from the most recent tag and the commit state, so releases and development builds stay consistent with the repository history.
Is setuptools-scm free to use? What license does it have?
setuptools-scm has no declared license. Its code is public, but without a license you have no explicit permission to reuse it; ask the author before relying on it.
Is setuptools-scm still maintained?
Actively maintained. The last commit to setuptools-scm was on Nov 4, 2026.
What can I use setuptools-scm for?
Keeping Python package versions tied to Git tags without editing version strings by hand. Versioning a Python project that is tracked in Git or Mercurial. Reusing VCS-based version detection in tooling that does not use setuptools.
How do I install setuptools-scm?
Install all packages and dependency groups with uv: uv sync --all-packages --all-groups Run the test suite: uv run pytest -n12
Where can I get setuptools-scm?
The source code and installation instructions are on GitHub: https://github.com/pypa/setuptools-scm

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects