setuptools-scm Documentation

setuptools-scm is a tool that extracts Python package versions from git or hg (Mercurial) metadata. Instead of manually declaring a version string in your source code or a managed file, setuptools-scm infers it from your Version Control System (VCS) state.

Key Features:

• Automatic Versioning: Uses VCS tags and history to determine the current version.
• SCM-managed File Inclusion: Automatically adds all files tracked by your SCM to the source distribution (sdist).

⚠️ Important Security/Cleanup Note: Because it automatically includes all SCM-tracked files in your source distributions, any development files tracked in Git/Mercurial will be included in your package. To prevent unwanted files from being shipped, you must use a MANIFEST.in file to exclude them or configure Git archive settings.

The setuptools-scm monorepo contains two primary projects:

1. setuptools-scm: The main package used to extract Python package versions from Git or Mercurial metadata, providing seamless integration with setuptools.
2. vcs-versioning: A standalone library containing the core VCS versioning logic, which can be used independently of setuptools.

For specific usage instructions, refer to the individual project documentation.

By default, setuptools-scm generates versions with local segments (e.g., +g1a2b3c4d5 or +dirty) which are not allowed on PyPI per PEP 440. To prepare for publishing, use the SETUPTOOLS_SCM_OVERRIDES_FOR_${DIST_NAME} environment variable to override the local_scheme.

Recommended Schemes:

• no-local-version-strict: Use for release builds. It strips the local segment and fails the build if the working tree is dirty, preventing accidental pollution.
• no-local-version: Use for development/nightly uploads (e.g., to test-PyPI) where a dirty tree is acceptable. It strips the local segment but allows the build to proceed.

Directly calling setuptools_scm.get_version() at runtime is strongly discouraged. You should use importlib.metadata instead.

However, if you must use it (e.g., for legacy Sphinx configurations or specific development environments), you may need to provide root and fallback_root parameters to ensure it works correctly when the SCM metadata is not present (like in extracted tarballs) or when the script is running from a subdirectory.

from setuptools_scm import get_version

# Use root for when SCM metadata is present
# Use fallback_root for when SCM metadata is missing (e.g. in archives)
version = get_version(root='..', fallback_root='..', relative_to=__file__)

setuptools-scm is built on top of vcs-versioning.

• vcs-versioning (core library): Handles the heavy lifting of version extraction from Git, Mercurial, and Jujutsu, including version scheme logic, tag parsing, and formatting. These features are universal and work across different build systems.
• setuptools-scm (integration layer): Provides the setuptools-specific integration, such as build-time hooks, automatic file finder registration, and generating version files during the build process.

The experimental API uses a specific priority order when resolving configuration. This ensures users can always override settings via environment variables, while still allowing integrators to provide defaults.

Priority Order (Highest to Lowest):

1. Environment TOML overrides: Set via [TOOL_PREFIX]_OVERRIDES_FOR_[DIST] or [TOOL_PREFIX]_OVERRIDES.
2. Integrator overrides: Python arguments passed directly to build_configuration_from_pyproject().
3. Config file: Settings found in the [tool.vcs-versioning] section of pyproject.toml.
4. Defaults: The internal default values of vcs-versioning.

By default, setuptools-scm provides a setuptools file finder entry point. This means that when setuptools-scm is installed in your build environment, it automatically includes all SCM-tracked files in your source distributions (sdist) without requiring a MANIFEST.in file.

Controlling file inclusion

If you need to exclude specific files from the automatic inclusion, use one of the following methods:

1. MANIFEST.in: Use exclude or recursive-exclude for specific files or patterns.
2. Git Archive Configuration: Use export-ignore in .gitattributes (e.g., tests/ export-ignore).
3. Mercurial Configuration: Use .hgignore.

The version is calculated based on the latest tag, the distance from that tag, and the workdir state (uncommitted changes).

• {next_version} is the last tag's numeric component + 1.
• For Git, the hash is prefixed with g (e.g., g1a2b3c4d5).
• Important: Always include a patch version in your tags (e.g., 1.2.3 instead of 1.2) to ensure SemVer increments correctly.

The public experimental API specifically looks for the [tool.vcs-versioning] section in pyproject.toml. While setuptools_scm may use [tool.setuptools_scm] for backward compatibility, integrators using the new API must use the vcs-versioning key.

# ✅ Correct
[tool.vcs-versioning]
version_scheme = "guess-next-dev"
local_scheme = "no-local-version"

# ❌ Wrong for the public experimental API
[tool.setuptools_scm]
version_scheme = "guess-next-dev"