setuptools-scm

the blessed package to manage your versions by scm tags

setuptools-scm Permissive license MIT Active ★ 951 v10.2.1 released 2026-07-21

Install

setuptools-scm on PyPI

pip

pip install setuptools-scm

uv

uv add setuptools-scm

poetry

poetry add setuptools-scm

Package facts

License	MIT (permissive)
Python support	supports the current Python release (>=3.8)
Install friction	low — pure-Python wheel
Runtime dependencies	5 — vcs-versioning, packaging, setuptools, tomli, typing-extensions
Maintenance	actively maintained — 23 days since the last release
Last repo commit	2026-08-13
First released	2015-02-23
Popularity	one of the top 1,000 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

Evidence: setuptools_scm-10.2.1-py3-none-any.whl

Development Status :: 5 - Production/StableIntended Audience :: DevelopersProgramming Language :: PythonProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Topic :: Software Development :: LibrariesTopic :: Software Development :: Version ControlTopic :: System :: Software DistributionTopic :: Utilities

About setuptools-scm

from the package's own PyPI description — quoted content, verbatim

setuptools-scm

github ci (image) Documentation Status (image) tidelift (image)

about

[setuptools-scm] extracts Python package versions from git or hg metadata instead of declaring them as the version argument or in a Source Code Managed (SCM) managed file.

Additionally [setuptools-scm] provides setuptools with a list of files that are managed by the SCM <br/> (i.e. it automatically adds all the SCM-managed files to the sdist). <br/> Unwanted files must be excluded via MANIFEST.in or [configuring Git archive][git-archive-docs].

> ⚠️ Important: Installing setuptools-scm automatically enables a file finder that includes all SCM-tracked files in your source distributions. This can be surprising if you have...

Read as markdown · JSON record · Source repository · Docs

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

setuptools-scm extracts Python package versions automatically from git or Mercurial metadata during build, eliminating manual version declarations and automatically including all SCM-tracked files in source distributions.

Low install friction with a pure-wheel distribution and only five runtime dependencies. Active maintenance with a recent release (23 days ago) and consistent repository activity; supports Python 3.8–3.14.

MIT license permits unrestricted use, modification, and distribution with minimal obligations—suitable for both open-source and proprietary projects.

Usage

# In pyproject.toml:
[build-system]
requires = ["setuptools>=80", "setuptools-scm>=8"]
build-backend = "setuptools.build_meta"

[project]
dynamic = ["version"]

[tool.setuptools_scm]

# Then run:
python -m setuptools_scm

Requires setuptools >=61 (recommended >=80) and a git or Mercurial repository initialized in the project directory; version inference depends on SCM tags being present.

Verdict: setuptools-scm is a mature, actively maintained tool (951 GitHub stars, no known vulnerabilities) that simplifies Python package versioning by deriving it from VCS metadata. Its low install friction and permissive MIT license make it a safe choice for build pipelines, though users must be aware that it automatically includes all SCM-tracked files in distributions—exclusions must be configured explicitly via MANIFEST.in.

Needs verification

Whether the package's automatic file-inclusion behavior has caused unexpected distribution bloat in real-world projects and how common such issues are.
Performance impact when used with very large git repositories or complex SCM histories.

automatic version from git tagsscm-based python versioningsetuptools version managementgit metadata version extractiondynamic python package versioningmercurial version control integrationbuild-time version inference