setuptools-scm
raw JSON → 10.0.5 verified Tue May 12 auth: no python install: verified quickstart: stale
A package that manages your Python package versions using SCM tags, currently at version 10.0.5, with a release cadence of regular updates.
pip install setuptools-scm Common errors
error LookupError: setuptools-scm was unable to detect a version for 'your_package_name' ↓
cause `setuptools-scm` cannot find Git/Hg metadata (e.g., `.git` directory, tags) or a `_version.py` file during a build process, often in a clean environment or from a source distribution.
fix
Ensure the build environment contains the SCM repository metadata (e.g., by performing a full Git clone). For source distributions, ensure
_version.py is generated and included in the distribution by setting write_to in pyproject.toml (e.g., write_to = "src/your_package_name/_version.py"). error ModuleNotFoundError: No module named 'setuptools_scm' ↓
cause The `setuptools_scm` package is not installed in the build environment, preventing `setuptools` from using it as a version management backend.
fix
Add
'setuptools-scm' to the build-system.requires list in your pyproject.toml file to ensure it is installed as a build dependency, or explicitly install it via pip install setuptools-scm. error UserWarning: setuptools_scm was unable to detect a version for 'your_package_name'. ↓
cause `setuptools-scm` found a Git/Hg repository but could not reliably determine the version string, often due to missing tags, a dirty working tree, or a shallow clone without sufficient history.
fix
Ensure your Git/Hg repository has a version tag (e.g.,
git tag v1.0.0), commit any pending changes, perform a full clone, or configure setuptools-scm in pyproject.toml to handle dirty states or untagged commits gracefully (e.g., local_scheme = "dirty-tag" or fallback_version). Warnings
breaking Support for setuptools versions prior to 80 is deprecated and will be removed in a future release. ↓
fix Upgrade setuptools to version 80 or later.
gotcha Editable installs may break due to changes in '__editable__' and '__path_hook__'. ↓
fix Ensure compatibility with the latest setuptools version or adjust your installation method.
breaking setuptools-scm was unable to detect the package version, likely due to a missing .git directory or building from a source archive without version metadata. This often happens when installing from a plain zip download of a repository. ↓
fix Ensure the project is built from a complete git repository (including the .git directory) or an official PyPI tarball. If using pip for direct repository installs, use 'git+https://' URLs (e.g., git+https://github.com/user/proj.git#egg=proj). Alternatively, set the version using the environment variable 'SETUPTOOLS_SCM_PRETEND_VERSION_FOR_<NORMALIZED_DIST_NAME>'.
breaking setuptools-scm was unable to detect the project version. This typically occurs when the build environment lacks a complete Git repository (missing the .git folder) or when building from non-standard source distributions. ↓
fix Ensure the build source is a complete Git repository or a PyPI tarball. Alternatively, set the version using the environment variable SETUPTOOLS_SCM_PRETEND_VERSION_FOR_${NORMALIZED_DIST_NAME} before building.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - 0.26s 19.6M
3.10 slim (glibc) - - 0.17s 20M
3.11 alpine (musl) - - 0.40s 21.2M
3.11 slim (glibc) - - 0.33s 22M
3.12 alpine (musl) - - 0.33s 22.0M
3.12 slim (glibc) - - 0.32s 22M
3.13 alpine (musl) - - 0.27s 21.6M
3.13 slim (glibc) - - 0.27s 22M
3.9 alpine (musl) - - 0.90s 19.6M
3.9 slim (glibc) - - 0.77s 20M
Imports
- get_version
from setuptools_scm import get_version
Quickstart stale last tested: 2026-04-23
import os
from setuptools_scm import get_version
# Retrieve the version number
version = get_version(root=os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
print(f'Version: {version}')