Repository files navigation

setuptools-scm extracts Python package versions fromgit orhg metadatainstead of declaring them as the version argumentor in a Source Code Managed (SCM) managed file.

Additionallysetuptools-scm providessetuptools with a list offiles that are managed by the SCM
(i.e. it automatically adds all the SCM-managed files to the sdist).
Unwanted files must be excluded viaMANIFEST.inorconfiguring Git archive.

⚠️ Important: Installing setuptools-scm automatically enables a file finder that includesall SCM-tracked files in your source distributions. This can be surprising if you have development files tracked in Git/Mercurial that you don't want in your package. UseMANIFEST.in to exclude unwanted files. See thedocumentation for details.

The preferred way to configuresetuptools-scm is to authorsettings in atool.setuptools_scm section ofpyproject.toml.

This feature requires setuptools 61 or later (recommended: >=80 for best compatibility).First, ensure thatsetuptools-scm is present during the project'sbuild step by specifying it as one of the build requirements.

[build-system]requires = ["setuptools>=80","setuptools-scm>=8"]build-backend ="setuptools.build_meta"

That will be sufficient to requiresetuptools-scm for projectsthat supportPEP 518 likepip andbuild.

To enable version inference, you need to set the versiondynamically in theproject section ofpyproject.toml:

[project]# version = "0.0.1"  # Remove any existing version parameter.dynamic = ["version"][tool.setuptools_scm]

!!! note "Simplified Configuration"

Starting with setuptools-scm 8.1+, if `setuptools_scm` (or `setuptools-scm`) ispresent in your `build-system.requires`, the `[tool.setuptools_scm]` sectionbecomes optional! You can now enable setuptools-scm with just:```toml title="pyproject.toml"[build-system]requires = ["setuptools>=80", "setuptools-scm>=8"]build-backend = "setuptools.build_meta"[project]dynamic = ["version"]```The `[tool.setuptools_scm]` section is only needed if you want to customizeconfiguration options.

Additionally, a version file can be written by specifying:

[tool.setuptools_scm]version_file ="pkg/_version.py"

Wherepkg is the name of your package.

If you need to confirm which version string is being generated or debug the configuration,you can installsetuptools-scm directly in your working environment and run:

$python -m setuptools_scm#To explore other options, try:$python -m setuptools_scm --help

For further configuration see thedocumentation.

Some enterprise distributions like RHEL7ship rather old setuptools versions.

In those cases its typically possible to build by using an sdist againstsetuptools-scm<2.0.As those old setuptools versions lack sensible types for versions,modernsetuptools-scm is unable to support them sensibly.

It's strongly recommended to build a wheel artifact using modern Python and setuptools,then installing the artifact instead of trying to run against old setuptools versions.

!!! note "Legacy Setuptools Support"While setuptools-scm recommends setuptools >=80, it maintains compatibility with setuptools 61+to support legacy deployments that cannot easily upgrade. Support for setuptools <80 is deprecatedand will be removed in a future release. This allows enterprise environments and older CI/CD systemsto continue using setuptools-scm while still encouraging adoption of newer versions.

Everyone interacting in thesetuptools-scm project's codebases, issuetrackers, chat rooms, and mailing lists is expected to follow thePSF Code of Conduct.

To report a security vulnerability, please use theTidelift security contact.Tidelift will coordinate the fix and disclosure.