setuptools-scm "Unable to detect version" / "no version found" in CI

A package derives its version from git tags via setuptools-scm, and in CI there are no tags to read - usually because the checkout is shallow or not a git repo at all, so version detection fails.

What this error means

A build fails with LookupError: setuptools-scm was unable to detect version or it produces a wrong 0.0.0/...dev0+unknown version. It is common on GitHub Actions, where the default checkout is shallow and omits tags.

Build output

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

Make sure you're either building from a fully intact git repository or PyPI
tarballs. Most other sources (such as GitHub's tarballs ...) don't contain the
necessary metadata and will not work.

Common causes

Shallow clone without tags

The default actions/checkout does a shallow fetch with no tags. setuptools-scm has nothing to compute a version from.

Building outside a git checkout

Building from a non-git source (a downloaded tarball, a copied directory) means there is no SCM metadata at all.

How to fix it

Fetch full history and tags in CI

.github/workflows/ci.yml

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

Provide a fallback version

When SCM metadata is genuinely unavailable, give setuptools-scm a fallback so the build still succeeds.

pyproject.toml

# pyproject.toml
[tool.setuptools_scm]
fallback_version = "0.0.0"
# or via env
export SETUPTOOLS_SCM_PRETEND_VERSION=1.2.3

How to prevent it

Use fetch-depth: 0 for jobs that build versioned artifacts.
Ensure at least one tag exists for setuptools-scm to read.
Set fallback_version/SETUPTOOLS_SCM_PRETEND_VERSION for non-git builds.