pip "metadata-generation-failed" - Fix Backend Metadata Errors

pip asked the package’s build backend to produce its metadata and that step failed. The real error - an outdated setuptools, a broken setup.py, or a missing build dependency - is printed just above the wrapper.

What this error means

During "Preparing metadata (pyproject.toml)" pip stops with error: metadata-generation-failed and "Encountered error while generating package metadata". Nothing installs because pip can’t even read the package’s metadata.

pip output

  × Encountered error while generating package metadata.
  ╰─> [6 lines of output]
      ...
      ModuleNotFoundError: No module named 'setuptools'
      [end of output]
  note: This is an issue with the package mentioned above, not pip.
error: metadata-generation-failed

Common causes

Outdated or missing build tooling

A too-old setuptools/wheel, or none at all in an isolated build env, makes metadata generation fail. Newer packages need recent build backends.

A broken or non-PEP 517 setup.py

A setup.py that errors at import time (running code, importing the package itself, reading a missing file) fails during metadata generation.

How to fix it

Upgrade the build tooling

Terminal

python -m pip install --upgrade pip setuptools wheel
pip install <package>

Read the real backend error

Look at the captured output between the box-drawing lines - that is the backend’s real error.
For "No module named setuptools", upgrade pip/setuptools as above.
For a failing setup.py, fix the import-time code or pin a release that builds cleanly.

How to prevent it

Upgrade pip, setuptools, and wheel early in CI.
Avoid running side-effecting code at import time in setup.py.
Pin dependencies to releases that build on your Python version.