setuptools-scm
the blessed package to manage your versions by scm tags
Decision gist · record as of 2026-08-14
Yes. setuptools-scm is production-stable, actively maintained, widely used (top 1000 on PyPI), has no known vulnerabilities, and solves a real problem—eliminating manual version management. Install it as a build requirement in pyproject.toml if you use git or Mercurial for version control and want to avoid hardcoding versions. Be aware that it includes all SCM-tracked files in distributions by default; use MANIFEST.in to exclude unwanted files if needed.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires setuptools 61 or later (80+ recommended); project must be in a git or Mercurial repository for version extraction to work.
- Low friction install with five runtime dependencies.
- Actively maintained with a release 24 days ago and ongoing commits; last commit 2026-08-13.
License · maintenance · safety
MIT (permissive) — MIT license permits commercial and private use with minimal restrictions; suitable for most projects.
last release 2026-07-21 (24 days) · last repo commit 2026-08-13 · 951 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 134,189,099 downloads/mo, #285 on PyPI
Alternatives
Verify before relying
# In pyproject.toml:
[build-system]
requires = ["setuptools>=80", "setuptools-scm[simple]>=9.2"]
build-backend = "setuptools.build_meta"
[project]
dynamic = ["version"]
# Then run:
python -m setuptools_scm- Whether the automatic file-inclusion behavior (all SCM-tracked files in sdist) has caused issues in real deployments beyond the documented MANIFEST.in workaround.
- Performance impact when used with very large git repositories or complex SCM histories.
What it is and what it does
setuptools-scm is a build-time tool that derives your Python package's version directly from version control system tags (git or Mercurial) rather than requiring you to maintain a hardcoded version string in your code or configuration. It integrates with setuptools to automate version management during the build process, eliminating the need to manually sync version numbers across multiple files.
The package also automatically discovers and includes all SCM-tracked files in your source distributions (sdist), which can be a convenience but requires explicit exclusion via MANIFEST.in if you have development-only files tracked in version control. It depends on setuptools, packaging, tomli, typing-extensions, and a vcs-versioning abstraction layer. Configuration happens in pyproject.toml under [tool.setuptools_scm], and as of version 9.2+, minimal configuration can be omitted entirely when using the simple extra.
Use it for
- Eliminate manual version bumping in setup.py or pyproject.toml by deriving versions automatically from git tags during package builds.
- Ensure source distributions include all development files tracked in git without manually listing them in MANIFEST.in.
- Support CI/CD pipelines that tag releases in git and need the version reflected in built wheels and sdists without extra configuration steps.
- Maintain version consistency across multiple Python projects in a monorepo by using a single git tag strategy.
- Build packages in enterprise environments with older setuptools (61+) while gradually upgrading to modern setuptools versions.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
setuptools-scm is production-stable, actively maintained, widely used (top 1000 on PyPI), has no known vulnerabilities, and solves a real problem—eliminating manual version management. Install it as a build requirement in pyproject.toml if you use git or Mercurial for version control and want to avoid hardcoding versions. Be aware that it includes all SCM-tracked files in distributions by default; use MANIFEST.in to exclude unwanted files if needed.
Install
setuptools-scm on PyPI
Before you install
Low friction install with five runtime dependencies. Actively maintained with a release 24 days ago and ongoing commits; last commit 2026-08-13. Recommended for setuptools 80+, though compatible with setuptools 61+ for legacy environments.
Requires setuptools 61 or later (80+ recommended); project must be in a git or Mercurial repository for version extraction to work.
License in practice
MIT license permits commercial and private use with minimal restrictions; suitable for most projects.
Quickstart
# In pyproject.toml:
[build-system]
requires = ["setuptools>=80", "setuptools-scm[simple]>=9.2"]
build-backend = "setuptools.build_meta"
[project]
dynamic = ["version"]
# Then run:
python -m setuptools_scmVerify before relying
- Whether the automatic file-inclusion behavior (all SCM-tracked files in sdist) has caused issues in real deployments beyond the documented MANIFEST.in workaround.
- Performance impact when used with very large git repositories or complex SCM histories.
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.8 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 5 packagesvcs-versioningpackagingsetuptoolstomlityping-extensions |
| Maintenance | Actively maintained 24 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 134,189,099 / month, #285 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | 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 |
Evidence: setuptools_scm-10.2.1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “scm-based versioning”
- setuptools-scmAutomatically extracts and manages Python package versions from git…
- setuptools-git-versioningAutomatically generates PEP 440-compliant version numbers for Python…
- bump-my-versionAutomates version number management in projects by parsing,…
Give your agent the search over MCP, or paste the wish link into any chat.
More Libraries packages
urllib3 is an HTTP client library that provides thread-safe connection pooling, SSL/TLS verification, multipart file uploads, request retries, compression support, and proxy handling for Python applications.
Requests is a Python HTTP library that simplifies sending HTTP/1.1 requests with automatic handling of headers, authentication, cookies, and response parsing.
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
Provides parsing, arithmetic, and recurrence rule computation for dates and times, with timezone support and iCalendar RFC compliance.
Install it if you need to parse flexible date strings, compute relative dates, handle timezones, or work with recurrence rules—it's the de facto choice for these tasks.
Six provides utility functions to write Python code that runs on both Python 2.7 and Python 3.3+, smoothing over language differences between the two versions.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
See also read-version · setuptools-git-versioning · setuptools-scm-git-archive · vcver · versioningit · flit-scm · setuptools-git · twine · mercurial · hatch-vcs