pypi / setuptools-scm
setuptools-scm
What changed in setuptools-scm 8 to 10, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-13.
9 breaking1 security1 deprecations11 new APIs and options7 behavior and defaults2 tooling21 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initsetuptools-scm 1022 changes
Breaking changes 4
The required vcs-versioning version is now at least 2.5.0, avoiding an ImportError during builds when the file-discovery fix is used.
The minimum supported vcs-versioning version is now 2.4.0, preventing ImportError when setuptools-scm is installed with an older version.
vcs-versioning>=2.3.2 is now required for pkginfo workdir discovery.
Wheel .dist-info no longer includes scm_version.json or scm_file_list.json; both remain in sdists for fallback discovery.
Deprecations 1
Invoking the entry point for a project that does not configure setuptools-scm now emits a DeprecationWarning; the entry point will be removed in a future major release.
New APIs and options 4
Written into egg-info directories during egg_info to enable sdist fallback version inference when no VCS is present.
Written into egg-info directories during egg_info to enable sdist fallback version inference when no VCS is present.
Overrides the write_to_source setting.
Controls whether version files are written to the source tree; when unset, a deprecation warning advises setting it explicitly before the default changes in a future major release.
Behavior and default changes 2
Pretended-version builds now write scm_file_list.json to egg-info to describe which files the checkout tracks.
Commands are wrapped only after version inference stores data on the distribution; projects not using version inference keep their cmdclass unchanged. Stale scm_version.json files in *.egg-info are no longer stripped from built wheels.
Fixes and other changes 11
File discovery now follows the checkout independently of the versioning root, so tracked files are included in distributions for projects with a subdirectory pyproject.toml.
Pretended versions now discover the workdir on demand when a consumer needs a file list, so SCM-tracked files are not silently dropped from the sdist or wheel.
Command mixins no longer carry a runtime base class and now preserve the project's command MRO, preventing the project's run() from being silently skipped.
The file-finders hook now runs inside a setuptools-scm override context, so this documented variable is no longer ignored when finding files.
The file-finders hook now runs inside a setuptools-scm override context, so this documented variable is no longer ignored when finding files.
Python 3.8 and 3.9 support is restored, allowing projects that still support these versions to use setuptools-scm as a build dependency.
Fixes a deprecation warning leak when checking whether to write to the source.
When normalize is false, the version is wrapped in setuptools.sic() so setuptools does not re-normalize it, preserving CalVer zero-padding and other non-canonical version strings.
Calls with an explicit Configuration remain compatible; the shim wires _config and VcsEnvironment onto the workdir.
Calls with an explicit Configuration remain compatible; the shim wires _config and VcsEnvironment onto the workdir.
Non-package version files are no longer written to build_lib, preventing root-level version files from being incorrectly included in wheels.
setuptools-scm 919 changes
Breaking changes 1
Node hashes now have consistent lengths across all SCM backends.
Security 1
Environment override finding now uses better normalization and offers typo suggestions.
New APIs and options 5
The
scmparameter supports nested SCM configuration.You can configure setuptools-scm to fail when submodules are missing.
The package now includes
py.typedto mark its typing information as available to type checkers.This environment variable lets you configure which Mercurial command setuptools-scm uses.
This environment variable lets you override individual ScmVersion fields.
Behavior and default changes 4
Dirty working directory timestamps now use file modification times instead of the current time.
Tags from a release action in the GitHub UI are now accepted.
The default version file template now includes the commit id.
version_keywordcan overrideinfer_versionwhen configuration differs.
Tooling 2
Entrypoints are selectable, enabling better extensibility.
A console_scripts entry point makes the CLI directly executable.
Fixes and other changes 6
setuptools-scm can now be enabled when it is a build requirement.
Git now uses the fallback version instead of
0.0when no version is found.The method now returns consistent UTC dates regardless of local timezone.
The CLI no longer infers a version when
--no-versionis given.Python version build tags from the SCM version are now passed to results properly.
The error message now gives clearer guidance about
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_*environment variables.
setuptools-scm 811 changes
Breaking changes 4
File finders were moved to a private module, changing their import location.
Python 3.7 is no longer supported.
The setuptools integration moved to a private subpackage, changing its import location.
version_file replaces write_to for configuring version-file output.
New APIs and options 2
Custom version schemes can be used outside setup.py.
The version template receives ScmVersion as the extra template variable scm_version.
Behavior and default changes 1
The environment used by run() uses a UTF-8-enabled locale.
Fixes and other changes 4
Date-based calendar versioning handles v-prefixed tags.
Distribution names are normalized according to PEP 503 when looking for overrides.
The fallback behavior when SCM is missing was fixed.
An empty tag regex is handled.