setuptools_scm "Unable to detect version" - No Git Tags in CI

setuptools_scm derives the version from git history and tags. In CI, a shallow clone (--depth 1) or a tagless checkout leaves it nothing to read, so it errors or falls back to a 0.0.0-style placeholder.

What this error means

A build fails with LookupError: unable to detect version (or produces a bogus 0.1.dev0+... version) because git tags are not present in the CI checkout. It works locally where the full history and tags exist.

Build output

LookupError: setuptools-scm was unable to detect version for /home/runner/work/app.

Make sure you're either building from a fully intact git repository or PyPI tarballs.

Common causes

Shallow checkout without tags

CI often checks out with fetch-depth: 1 and no tags. setuptools_scm cannot find the nearest tag, so it cannot compute a version.

Building from an archive with no .git

Building from an exported tarball or a copied tree strips the .git directory, leaving setuptools_scm no metadata at all.

How to fix it

Fetch full history and tags

On GitHub Actions, deepen the checkout and fetch tags so setuptools_scm can resolve the version.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # full history
    fetch-tags: true

Pin the version when git is unavailable

When building outside a git tree, hand setuptools_scm a version via env so it does not need history.

Terminal

export SETUPTOOLS_SCM_PRETEND_VERSION=1.4.0
python -m build

How to prevent it

Use fetch-depth: 0 and fetch-tags: true for builds that version from git.
Tag releases so a nearest-tag always exists.
Set SETUPTOOLS_SCM_PRETEND_VERSION for tagless archive builds.