NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #301 most downloaded on PyPI
the blessed package to manage your versions by scm tags
Last release 11 days ago
23 Sep 2026
Release timing varies
gaps range from 8 days to 5 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
18 versions withdrawn
withdrawn after publishing
12 years old
114 releases · first in 2015
Ship the tracked files of projects whose pyproject.toml sits in a subdirectory of the checkout. root defaults to the project directory, so version inf
Ship the tracked files of projects whose pyproject.toml sits in a subdirectory
of the checkout. root defaults to the project directory, so version inference
correctly finds no SCM there and answers from SETUPTOOLS_SCM_PRETEND_VERSION
or fallback_version -- but that says nothing about which files git tracks, and
the sdist and wheel came out with none of them. This was the 10.3.0 regression
fixed in 10.3.3, surviving in the subdirectory layout.
File discovery now follows the checkout the project sits in, independently of
the root that scopes versioning, and records scm_file_list.json in the
egg-info as a root-level project already did. (#1543)
Require vcs-versioning>=2.5.0. The subdirectory file-discovery fix (#1543) imports
discover_file_workdir, which no earlier release has, while the declared floor still
named 2.4.0 -- an install against a published vcs-versioning raised ImportError
during the build. (#1546)
One column per quarter.
Keep file discovery working when the version is pretended. SETUPTOOLS_SCM_PRETEND_VERSION and its scoped _FOR_<DIST> form made version inference retur
Keep file discovery working when the version is pretended.
SETUPTOOLS_SCM_PRETEND_VERSION and its scoped _FOR_<DIST> form made
version inference return before discovering a workdir, and the egg_info
mixin read the absent workdir as "searched, found no checkout" -- the signal
it acts on by suppressing the setuptools.file_finders chain. Every
SCM-tracked file that setuptools' own package discovery does not find was
then dropped from the sdist and the wheel, silently, since the build
succeeded and the version was correct.
A pretended version still skips discovery, because most builds only want a
version and probing for a checkout nobody asks about costs subprocesses for
nothing. What no longer happens is passing that off as an answer: "nobody
looked yet" is now distinct from "looked and found nothing", and the workdir
is discovered on demand the first time a consumer needs a file list.
scm_file_list.json is now written to the egg-info for pretended builds as
well. It describes which files the checkout tracks, which a pretended
version says nothing about. scm_version.json stays absent there, because
a pretended version must not be recorded as what the SCM said. (#1540)
Stop the command mixins from reordering a project's own build_py , egg_info or bdist_wheel MRO. ScmVersionFileMixin and friends inherited from the cor
Stop the command mixins from reordering a project's own build_py, egg_info
or bdist_wheel MRO. ScmVersionFileMixin and friends inherited from the
corresponding setuptools command, so wrapping a project class built on a disjoint
hierarchy -- distutils.command.build_py, or the standalone wheel package's
bdist_wheel -- placed setuptools' command ahead of the project's class.
setuptools.build_py.run() does not delegate any further, so the project's
run() was silently skipped, surfacing as
error: package directory '...' does not exist. The mixins now carry no runtime
base class and linearise to (wrapped, mixin, *project_command.__mro__). (#1531)
Leave a project's cmdclass alone when setuptools-scm is installed but not
actually inferring a version. build_py, egg_info and bdist_wheel are
now registered only once version inference has stored data on the distribution --
the precondition for any of the mixins doing something. Previously every project
with a pyproject.toml had its commands wrapped, including projects with no
[tool.setuptools_scm] section at all.
Note for projects that used to configure setuptools-scm and no longer do: a
scm_version.json left behind in a stale *.egg-info directory is no longer
stripped from built wheels, because the bdist_wheel mixin that strips it is no
longer registered either. Remove the stale *.egg-info directory. (#1533)
Require vcs-versioning>=2.4.0 . setuptools-scm 10.3.0 declared >=2.3.2 but imports vcs_versioning._file_finders.scm_search_known_failed , which vcs-ve
vcs-versioning>=2.4.0. setuptools-scm 10.3.0 declared >=2.3.2 butvcs_versioning._file_finders.scm_search_known_failed, which vcs-versioningImportError. CI now installs setuptools-scm against the oldest vcs-versioning itsEmit a DeprecationWarning when the setuptools.file_finders entry point is invoked for a project that does not configure setuptools-scm. The entry poin…
DeprecationWarning when the setuptools.file_finders entry point is invoked for a project that does not configure setuptools-scm. The entry point will be removed in a future major release. (#1407)Run the setuptools.file_finders hook inside a setuptools-scm override context. It previously resolved settings under the VCS_VERSIONING prefix only, so documented variables such as SETUPTOOLS_SCM_SUBPROCESS_TIMEOUT and SETUPTOOLS_SCM_HG_COMMAND were ignored when finding files.
When version inference has already run and found no SCM checkout, the egg_info mixin now tells the file finders so, rather than letting walk_revctrl() re-probe every backend for a repository known to be absent. (#1212)
Do not run the xmlsec download regression test on Python 3.8, where no lxml wheel exists and --no-build-isolation leaves pip without a build toolchain
--no-build-isolation leaves pip without a build toolchain for the lxml sdist. (#1516)The pkginfo workdir discovery entry point moved to vcs-versioning; vcs-versioning>=2.3.2 is now required (the workspace pin carries a .dev0 suffix so
pkginfo workdir discovery entry point moved to vcs-versioning; vcs-versioning>=2.3.2 is now required (the workspace pin carries a .dev0 suffix so in-tree builds resolve, matching the existing convention). setuptools_scm._integration._discover.discover_pkginfo remains as a re-export. (#1507)uv.lock in the sdist. It could not be generated correctly whenever setuptools-scm required an unreleased vcs-versioning, which broke the release proposal workflow. (#1509)Omit scm_version.json and scm_file_list.json from wheel .dist-info while still including them in sdists for fallback discovery.
scm_version.json and scm_file_list.json from wheel .dist-infoRestore Python 3.8 and 3.9 support, re-enabling use as a build dependency for projects like scikit-build that still support these versions.
project_root from egg_info to the workdir so file discovery is correctly scoped in monorepo setups. (#1440)Fix DeprecationWarning leak by threading VcsEnvironment through VersionInferenceConfig and using env.make_reader() in _should_write_to_source.
Update CI to use PyPy 3.11 as cryptography has no PyPy 3.10 build available
Allow dump_version() deprecation warning to be silenced by passing scm_version=None.
Anchor get_version in setup.py with relative_to and fallback_root so SCM fallbacks (e.g. PKG-INFO) do not resolve against the wrong directory when the
get_version in setup.py with relative_to and fallback_root so SCM fallbacks (e.g. PKG-INFO) do not resolve against the wrong directory when the build cwd is the workspace or repo root. (#1302)GlobalOverrides for SETUPTOOLS_SCM when using setuptools_scm.get_version / _get_version, avoiding implicit context warnings for direct API callers. (#1314)Remove monorepo-only ../vcs-versioning/src from build-system.backend-path so sdists install under PEP 517 (paths must stay inside the source tree).
../vcs-versioning/src from build-system.backend-path so sdists install under PEP 517 (paths must stay inside the source tree). (#1306)griffecli to test dependencies so the API stability check keeps working after the Griffe CLI was split into a separate package. (#1310)Fix version file not generated for editable installs. Version files are now written to the source tree by default during inference (restoring pre-10.x
build_py outputs so strict editable installs include them in the persistent auxiliary directory. Set SETUPTOOLS_SCM_WRITE_TO_SOURCE=0 to disable source-tree writing (e.g., for read-only source directories). (#1298)Simplify release tag creation to use a single createRelease API call instead of separate createTag/createRef/createRelease calls, avoiding dangling ta
createRelease API call instead of separate createTag/createRef/createRelease calls, avoiding dangling tag objects on partial failures. (#release-pipeline)<!-- Release notes generated using configuration in .github/release.yml at main -->
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.2.1...v9.2.2
tool.setuptools.dynamic.version when only using file finder.
The warning about combining version guessing with setuptools dynamic versions should only
be issued when setuptools-scm is performing version inference, not when it's only being
used for its file finder functionality.Fix 1216 explicitly deprecate setuptools dynamic version when active by @RonnyPfannschmidt in https://github.com/pypa/setuptools-scm/pull/1219
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.2.0...v9.2.1
version = attr: in setuptools config.
unfortunately dozens of projects cargo-culted that antipattern<!-- Release notes generated using configuration in .github/release.yml at main -->
<!-- Release notes generated using configuration in .github/release.yml at main -->
simple activation now requires a extra instead of setting up many pre-existing projects for failure/error
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.1.1...v9.2.0
add simplified activation via setuptools-scm[simple] extra
A new streamlined way to enable version inference without requiring a [tool.setuptools_scm] section.
When setuptools-scm[simple] is in build-system.requires and version is in project.dynamic,
version inference is automatically enabled with default settings.
<!-- Release notes generated using configuration in .github/release.yml at main -->
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.1.0...v9.1.1
yanked after hitting regressions wrt legcy project setups triggering auto activate
a regression makes some sdists report version 0.0.0
a regression makes some sdists report version 0.0.0
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.0.3...v9.1.0
complete reiteration of the decision logic for enabling version inference on setuptools_scm
<!-- Release notes generated using configuration in .github/release.yml at main -->
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.0.2...v9.0.3
regression wrt specific old project setups vs auto-activate
<!-- Release notes generated using configuration in .github/release.yml at main -->
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.0.1...v9.0.2
fix 1180 provide dummy scmversion for dump by @RonnyPfannschmidt in https://github.com/pypa/setuptools-scm/pull/1183
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v9.0.0...v9.0.1
fix #1019: pass python version build tags from scm version to results propperly
setuptools-scm console_scripts entry point to make the CLI directly executableSETUPTOOLS_SCM_HG_COMMANDSETUPTOOLS_SCM_PRETEND_METADATA environment variable to override individual ScmVersion fieldsscm parameter support to get_version() function for nested SCM configurationversion_keyword to override infer_version when configuration differsfallback_root parameter in programmatic usage and configurationpip to test optional dependencies for improved uv venv compatibility__all__ in the version template to sort<!-- Release notes generated using configuration in .github/release.yml at main -->
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v8.3.0...v8.3.1
<!-- Release notes generated using configuration in .github/release.yml at main -->
<!-- Release notes generated using configuration in .github/release.yml at main -->
Full Changelog: https://github.com/pypa/setuptools-scm/compare/v8.2.1...v8.3.0
fix #1119: also include pre/post release details in version_tuple
fix #960: add a --force-write-version-files flag for the cli
--force-write-version-files flag for the clicorrectly handle project config overrides when the version keyword is used together with pyproject.toml by @RonnyPfannschmidt in https://github.com/py
entangled-cli to account for not having rich extra by @jamesbraza in https://github.com/pypa/setuptools_scm/pull/980SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${NORMALIZED_DIST_NAME} by @jamesbraza in https://github.com/pypa/setuptools_scm/pull/981Full Changelog: https://github.com/pypa/setuptools_scm/compare/v8.0.4...v8.1.0
__all__ in autogenerated version.py files to aid IDE autoimportsintroduce scriv for changelog management
write_to to be an absolute path when it's a subdirectory of the rootDEFAULT_VERSION_SCHEME and DEFAULT_LOCAL_SCHEME on the setuptools-scm packageShare the stderr with the user, when non-zero exit code by @arvidma in https://github.com/pypa/setuptools_scm/pull/927
Full Changelog: https://github.com/pypa/setuptools_scm/compare/v8.0.2...v8.0.3
fix #914: ignore the deprecated git archival plugin by @RonnyPfannschmidt in https://github.com/pypa/setuptools_scm/pull/922
SETUPTOOLS_SCM_PRETEND_VERSION warning by @antazoey in https://github.com/pypa/setuptools_scm/pull/917Full Changelog: https://github.com/pypa/setuptools_scm/compare/v8.0.1...v8.0.2
git unshallow
to account for large repos or slow connectionsfix #905 - correct version file template for older python versions by @RonnyPfannschmidt in https://github.com/pypa/setuptools_scm/pull/907
Full Changelog: https://github.com/pypa/setuptools_scm/compare/v8.0.0...v8.0.1
Apply refurb suggestions by @DimitriPapadopoulos in https://github.com/pypa/setuptools_scm/pull/787
pypa/gh-action-pypi-publish to release/v1 by @webknjaz in https://github.com/pypa/setuptools_scm/pull/828ScmVersion to dump_version to provide scm_version as extra template variable by @ZhiyuanChen in https://github.com/pypa/setuptools_scm/pull/854Full Changelog: https://github.com/pypa/setuptools_scm/compare/v7.1.0...v8.0.0
distance=None and distance=0 they should mean the same andwhere hiding dirty states that are now explicitly dirtySETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DIST_NAME} env varversion_file as replacement for write_tosetuptools_scm to setuptools-scmcreated a directory for the vcs-versioning package and added it to pypi
git: expect main as possible default branch
drop version_from_scm helper
trim down exposed public api
no longer self-call twice in setuptools
add support for version schemes by import
chores
support passing log levels to SETUPTOOLS_SCM_DEBUG
support using rich.logging as console log handler if installed
fix #527: type annotation in default version template
fix #549: use fallbacks when scm search raises CommandNotFoundError
fix #762: handle non-ascii in setup.cfg
tomllib from stdlibfixes #742, #745: correctly handle accidentally released archival files
fix #727: correctly handle incomplete archival from setuptools_scm_git_archival
Hg / pip compatibility by @paugier in https://github.com/pypa/setuptools_scm/pull/729
Full Changelog: https://github.com/pypa/setuptools_scm/compare/v7.0.2...v7.0.3
fix #723 and #722: remove bootstrap dependencies
setup.cfg if needed even for pyproject.tomlfix #718: Avoid ModuleNotFoundError by requiring importlib_metadata in python<3.8
ModuleNotFoundError by requiring importlib_metadata in python<3.8fix #707: support git version detection even when git protects against mismatched owners (common with misconfigured containers, thanks @chrisburr )
log.showSignature is setfix #671: NoReturn is not available in painfully dead python 3.6
NoReturn is not available in painfully dead python 3.6fix regression #669: restore get_version signature
better handling of setuptools install command deprecation
pyproject.tomls when running as command--strip-dev flag to python -m setuptools_scm to print the next guessed version cleanlyfix #629: correctly convert Version data in tags_to_version parser to avoid errors
fix #625: restore tomli in install_requires after the regression changes in took it out and some users never added it even tho they have pyproject.tom
This mechanism has long since been deprecated and removed as most people haven\'t been using it
This release explicitly warns on unsupported setuptools. This
unfortunately has to happen as the legacy setup_requires mechanism
incorrectly configures the setuptools working-set when a more recent
setuptools version than available is required.
As all releases of setuptools are affected as the historic mechanism for
ensuring a working setuptools setup was shipping a ez_setup file next
to setup.py, which would install the required version of setuptools.
This mechanism has long since been deprecated and removed as most people haven't been using it
setup.py as wellfix #608: resolve tomli dependency issue by making it a hard dependency as all intended/supported install options use pip/wheel this is only a feature
fix #605: completely disallow bdist_egg - modern enough setuptools\>=45 uses pip
fix #587: don\'t fail file finders when distribution is not given
normalize and version_cls to customize
the version normalization class.mypkg/_version.pyv as release branchespackaging.version for version_tupleNothing published for this version
fix #537: drop node_date on old git to avoid errors on missing %cI
fix #517: drop dead python support \>3.6 required
fix #415: use git for matching prefixes to support the windows situation
fix #509: support SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DISTRIBUTION_NAME} for pyproject.toml
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DISTRIBUTION_NAME} for pyproject.tomlfix #339: strict errors on missing scms when parsing a scm dir to avoid false version lookups
Breaking changes:
Bugfixes:
no-guess-dev which does no next version guessing, just adds .post1.devN in
case there are new commits after the tagSETUPTOOLS_SCM_PRETEND_VERSION_FOR_${DISTRIBUTION_NAME} env var to target the pretend keydisallows numeric tags without a dot again, turns out this creates many issues for people, projects needing single digit versions need to explicitly a
disallows numeric tags without a dot again, turns out this creates many issues for people, projects needing single digit versions need to explicitly allow it
drop jaraco.windows from pyproject.toml, allows for wheel builds on python2
include python 3.9 via the deadsnakes action
Your coding agent can read these notes before it upgrades. Set up the MCP server →