setuptools_scm "no version found" with importlib.metadata Fallback

A project that derives its version from git via setuptools_scm reads that version at runtime through importlib.metadata. If it was built without tags or installed without metadata, the runtime lookup has nothing to return.

What this error means

A package using a dynamic setuptools_scm version crashes at import with a metadata/version error, or builds a wheel versioned 0.0.0/0.1.dev0+unknown. The build environment lacked git history, tags, or the .git directory.

Build output

LookupError: setuptools-scm was unable to detect version for /repo.
Make sure you're either building from a fully intact git repository or
PyPI tarballs. ... If using pip ... use a shallow clone with full tags.

Common causes

Shallow clone or missing tags at build time

CI checkouts are often shallow and tagless. setuptools_scm cannot derive a version without the tag history, so the build fails or stamps a placeholder.

No .git directory in the build context

Building from a tarball or a Docker context that excluded .git leaves setuptools_scm with no source of truth for the version.

How to fix it

Fetch full history and tags in CI

Give the checkout the tags setuptools_scm needs.

.github/workflows/ci.yml

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

Provide the version explicitly when git is unavailable

When building without git (tarball, Docker), pass the version via the documented env var so setuptools_scm does not need to detect it.

Terminal

export SETUPTOOLS_SCM_PRETEND_VERSION=1.4.2
pip install .

How to prevent it

Use fetch-depth: 0 for builds that derive a version from git.
Set SETUPTOOLS_SCM_PRETEND_VERSION when building outside a git tree.
Include .git in the Docker build context, or build the wheel before copying.