pip error: metadata-generation-failed (and subprocess-exited-with-error)
Modern pip wraps a package’s own setup crash in a long red banner. The banner is almost never the useful part — the traceback printed just above it is.
Read the traceback, ignore the banner
pip 21 and later isolate the build in a temporary environment, run the package’s setup.py or build backend, and if that process exits non-zero, print a stock note:
error: subprocess-exited-with-error
× Preparing metadata (pyproject.toml) did not run successfully.
│ exit code: 1
╰─> [this is only a summary]
note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failedThe sentence “likely not a problem with pip” is usually true: pip asked the project “what are you?” and the project crashed. The answer is in the first traceback above that block, not in the banner itself.
What “generating metadata” actually is
Before pip can decide which other packages to install, it needs the project’s name, version and install_requires. For a modern project that is prepare_metadata_for_build_wheel from pyproject.toml; for older ones it is python setup.py egg_info or “Getting requirements to build wheel”. No C code has been compiled yet. If the crash happens later, during the compile, you will see Failed building wheel instead.
The usual real errors
| What the traceback says | What it means | Fix |
|---|---|---|
fatal error: Python.h: No such file or directory | The C header for your Python is missing. Some setup.py files probe for it while collecting metadata. | Debian/Ubuntu: sudo apt install build-essential python3-dev (or python3.12-dev matching python -V). Fedora: python3-devel gcc. macOS: xcode-select --install. |
setuptools-scm was unable to detect version / LookupError: setuptools-scm | The project versions itself from git tags, but you installed from a zip, a GitHub “Download ZIP”, or a checkout with no tags. | Install a published sdist from PyPI, clone with git history, or set SETUPTOOLS_SCM_PRETEND_VERSION=1.2.3 for a local test. |
RuntimeError: Python 3.x is not supported (or an assert sys.version_info failure) | The package has refused to even describe itself on this Python. | Use a Python the package lists, or a newer package version. See also Could not find a version. |
An ImportError / ModuleNotFoundError inside setup.py | The setup script imports the package itself (or a build-only extra) at collection time. | For your own project, stop importing the package in setup.py and list build tools in [build-system] requires. For a third-party project, upgrade it or install a wheel so setup never runs. |
A failure installing setuptools, wheel, cython or hatchling in a temporary env | Build isolation could not satisfy build-system.requires. | Upgrade pip: python -m pip install -U pip setuptools wheel. Last resort, and only if you already installed those tools yourself: pip install --no-build-isolation PACKAGE. |
A short checklist
- Scroll to the first Python exception, not the red wrapper.
- Confirm which interpreter you are using:
python -Vandpython -m pip -Vshould name the same path (prefer a virtual environment). - Upgrade the installer:
python -m pip install -U pip setuptools wheel. - If the traceback mentions
Python.h,gccorclang, install the matching developer headers (table above). - If you are on Ubuntu 24.04 / Debian 12 and pip refused even to start, that is a different error: externally-managed-environment.
Pasting the raw traceback into a web form is rarely necessary; the first exception line is enough to search on. If you do want a second pair of eyes on “what kind of message is this?”, What is this? classifies a pasted blob in your browser.
Related
Failed building wheel · Microsoft Visual C++ 14.0 is required · ResolutionImpossible · Could not find a version · externally-managed-environment · venv not activating
Questions
What does pip metadata-generation-failed mean?
Pip downloaded the project but crashed while asking it for its name, version and dependencies, before compiling anything. The real reason is the Python traceback printed above the red banner.
Is “This error originates from a subprocess, and is likely not a problem with pip” true?
Usually yes. The subprocess is the package’s own setup or build backend. Fix whatever that traceback shows, rather than reinstalling pip on its own.
How is this different from Failed building wheel?
metadata-generation-failed happens while collecting name and requirements. Failed building wheel happens afterwards, when a compiler is turning source into a wheel. They need different fixes.
What is setuptools-scm was unable to detect version?
The project reads its version from git tags, but your copy has no git metadata (a zip download, or an sdist that omitted the version file). Install the PyPI sdist or set SETUPTOOLS_SCM_PRETEND_VERSION.
Should I use pip install --no-build-isolation?
Only after you have installed the build tools yourself (setuptools, wheel, and whatever pyproject.toml lists) and isolation is the thing that failed. It is a workaround, not a first step.
Does this mean the package does not exist on PyPI?
No. That message is Could not find a version that satisfies the requirement / No matching distribution found, which is a different guide.
Published .