# What changed in setuptools-scm

> 56 changes in setuptools-scm 8 to 10 from its official release notes, upgrade guides and advisories: 9 breaking, 1 deprecations, 1 security, 11 new APIs and options. Each one cited. Sources checked 2026-11-13. HTML: https://unstale.sh/pypi/setuptools-scm/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## setuptools-scm 10

### Breaking changes

- The required vcs-versioning version is now at least 2.5.0, avoiding an ImportError during builds when the file-discovery fix is used. (10.3.4) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.4)
- The minimum supported vcs-versioning version is now 2.4.0, preventing ImportError when setuptools-scm is installed with an older version. (10.3.1) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.1)
- vcs-versioning>=2.3.2 is now required for pkginfo workdir discovery. (10.2.2) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.2.2)
- Wheel .dist-info no longer includes scm_version.json or scm_file_list.json; both remain in sdists for fallback discovery. (10.2.1) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.2.1)

### Deprecations

- 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. (10.3.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.0)

### New APIs and options

- Written into egg-info directories during egg_info to enable sdist fallback version inference when no VCS is present. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)
- Written into egg-info directories during egg_info to enable sdist fallback version inference when no VCS is present. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)
- Overrides the write_to_source setting. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)
- 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. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)

### Behavior and default changes

- Pretended-version builds now write scm_file_list.json to egg-info to describe which files the checkout tracks. (10.3.3) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.3)
- 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. (10.3.2) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.2)

### Fixes and other changes

- 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. (10.3.4) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.4)
- 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. (10.3.3) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.3)
- 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. (10.3.2) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.2)
- The file-finders hook now runs inside a setuptools-scm override context, so this documented variable is no longer ignored when finding files. (10.3.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.0)
- The file-finders hook now runs inside a setuptools-scm override context, so this documented variable is no longer ignored when finding files. (10.3.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.3.0)
- Python 3.8 and 3.9 support is restored, allowing projects that still support these versions to use setuptools-scm as a build dependency. (10.2.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.2.0)
- Fixes a deprecation warning leak when checking whether to write to the source. (10.1.2) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.2)
- 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. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)
- Calls with an explicit Configuration remain compatible; the shim wires _config and VcsEnvironment onto the workdir. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)
- Calls with an explicit Configuration remain compatible; the shim wires _config and VcsEnvironment onto the workdir. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)
- Non-package version files are no longer written to build_lib, preventing root-level version files from being incorrectly included in wheels. (10.1.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.1.0)
- Passing scm_version=None silences the deprecation warning from dump_version(). (10.0.5) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.0.5)
- Direct calls to get_version and _get_version now enter GlobalOverrides for SETUPTOOLS_SCM, avoiding implicit context warnings. (10.0.4) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.0.4)
- Anchoring get_version in setup.py with relative_to and fallback_root prevents SCM fallbacks from resolving against the wrong directory when the build runs from the workspace or repo root. (10.0.4) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.0.4)
- Removed the monorepo-only source path so sdists install under PEP 517, which requires paths to stay inside the source tree. (10.0.3) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/setuptools-scm-v10.0.3)

## setuptools-scm 9

### Breaking changes

- Node hashes now have consistent lengths across all SCM backends. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)

### Security

- Environment override finding now uses better normalization and offers typo suggestions. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)

### New APIs and options

- The `scm` parameter supports nested SCM configuration. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- You can configure setuptools-scm to fail when submodules are missing. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- The package now includes `py.typed` to mark its typing information as available to type checkers. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- This environment variable lets you configure which Mercurial command setuptools-scm uses. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- This environment variable lets you override individual ScmVersion fields. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)

### Behavior and default changes

- Dirty working directory timestamps now use file modification times instead of the current time. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- Tags from a release action in the GitHub UI are now accepted. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- The default version file template now includes the commit id. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- `version_keyword` can override `infer_version` when configuration differs. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)

### Tooling

- Entrypoints are selectable, enabling better extensibility. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- A console_scripts entry point makes the CLI directly executable. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)

### Fixes and other changes

- setuptools-scm can now be enabled when it is a build requirement. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- Git now uses the fallback version instead of `0.0` when no version is found. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- The method now returns consistent UTC dates regardless of local timezone. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- The CLI no longer infers a version when `--no-version` is given. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- Python version build tags from the SCM version are now passed to results properly. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)
- The error message now gives clearer guidance about `SETUPTOOLS_SCM_PRETEND_VERSION_FOR_*` environment variables. (9.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v9.0.0)

## setuptools-scm 8

### Breaking changes

- File finders were moved to a private module, changing their import location. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)
- Python 3.7 is no longer supported. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)
- The setuptools integration moved to a private subpackage, changing its import location. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)
- version_file replaces write_to for configuring version-file output. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)

### New APIs and options

- Custom version schemes can be used outside setup.py. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)
- The version template receives ScmVersion as the extra template variable scm_version. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)

### Behavior and default changes

- The environment used by run() uses a UTF-8-enabled locale. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)

### Fixes and other changes

- Date-based calendar versioning handles v-prefixed tags. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)
- Distribution names are normalized according to PEP 503 when looking for overrides. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)
- The fallback behavior when SCM is missing was fixed. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)
- An empty tag regex is handled. (8.0.0) — [release notes](https://github.com/pypa/setuptools-scm/releases/tag/v8.0.0)