pip "error: metadata-generation-failed" in CI

pip invoked the project's PEP 517 build backend to generate package metadata, but the backend exited non-zero before producing it. pip stops and reports metadata-generation-failed with the backend output above.

What this error means

pip prints "Preparing metadata (pyproject.toml) ... error" followed by a traceback from the build backend and ends with "error: metadata-generation-failed". It reproduces every run.

  error: subprocess-exited-with-error

  x Preparing metadata (pyproject.toml) did not run successfully.
  | exit code: 1
  +-> See above for output.

error: metadata-generation-failed

Common causes

A malformed or incomplete pyproject.toml

The [build-system] table is missing or [project] requires a field the backend cannot satisfy, so metadata preparation aborts.

A build dependency is missing

The backend imports a package (a versioning plugin, a Cython generator) that is not listed in build-system.requires, so it crashes before emitting metadata.

How to fix it

Read the backend traceback and fix the root cause

1. Scroll above the "metadata-generation-failed" line to the actual backend traceback.
2. If it is a missing import, add that package to build-system.requires.
3. If it is a config error, correct the offending pyproject.toml field.
4. Re-run the install to confirm metadata now generates.

[build-system]
requires = ["setuptools>=61", "setuptools-scm>=8"]
build-backend = "setuptools.build_meta"

Upgrade pip and build tooling

Old pip or setuptools can misread newer pyproject schemas; upgrade them before building.

python -m pip install --upgrade pip setuptools wheel

How to prevent it

• Build the sdist and wheel locally with python -m build before pushing.
• List every backend plugin in build-system.requires.
• Keep pip and setuptools current in CI.

Related guides