pip: Failed building wheel for … — what it really means
“Failed building wheel” is not one bug. It means pip could not find a ready-made binary for your Python and OS, tried to compile the project from source, and the compiler lost.
Why pip is compiling at all
PyPI typically publishes both a wheel (.whl: already built, tagged for a Python version, OS and CPU) and an sdist (.tar.gz: source). pip prefers a wheel. It only runs a compiler when no wheel tag matches — or when you pinned a version so old that wheels were never uploaded.
Check, in this order:
python -Vandpython -m pip -V(same interpreter; upgrade withpython -m pip install -U pip). Old pip does not understand newer wheel tags such asmanylinux_2_28ormusllinux, so it ignores perfectly good binaries and tries to compile.- The Download files tab on the package’s PyPI page. Look for a file like
package-…-cp313-cp313-manylinux*.whlor…-win_amd64.whlthat matches your Python and platform. - Whether you asked for a version, marker or extra that has no wheel. Relaxing a pin by one minor version often avoids a compiler entirely.
To make a missing wheel fail fast instead of compiling for three minutes: python -m pip install PACKAGE --only-binary=:all:.
If you really do need to compile
| Platform | Minimum tools |
|---|---|
| Debian / Ubuntu | sudo apt install build-essential python3-dev (add the versioned python3.12-dev if python -V is not the distro default) |
| Fedora / RHEL | sudo dnf install gcc python3-devel |
| Alpine | apk add build-base python3-dev linux-headers musl-dev. Many wheels are manylinux (glibc) only, so Alpine (musl) compiles far more often — or use a Debian-based image such as python:3.x-slim. |
| macOS | xcode-select --install for clang. Some scientific packages also need Homebrew libraries (brew install libjpeg libtiff libxml2). |
| Windows | This error usually appears as Microsoft Visual C++ 14.0 or greater is required. Prefer a wheel; the compiler toolchain is a multi-gigabyte install. |
Header packages for popular builds
The compiler is not enough when the project wraps an existing C library. The traceback will mention a missing .h file:
| You are installing | Typical missing header | Debian/Ubuntu package |
|---|---|---|
| Pillow | jpeglib.h, zlib.h | libjpeg-dev zlib1g-dev (plus libpng-dev libfreetype6-dev if those features are enabled) |
| lxml | libxml/xmlversion.h | libxml2-dev libxslt1-dev |
| psycopg2 | libpq-fe.h | libpq-dev (or install psycopg2-binary to avoid compiling) |
| cryptography (old versions) / older PyOpenSSL stacks | OpenSSL headers, or a Rust toolchain | libssl-dev libffi-dev pkg-config; current cryptography publishes wheels, so upgrade pip first |
| Anything with native extensions | Python.h | python3-dev matching this interpreter |
Related
metadata-generation-failed · Microsoft Visual C++ 14.0 is required · ResolutionImpossible · Could not find a version · Killed / exit 137 (out of memory) · externally-managed-environment
Questions
What does Failed building wheel mean in pip?
Pip could not use a pre-built binary for your Python and OS, so it tried to compile the project from source and the compiler failed. The useful detail is the gcc/clang/MSVC error above the summary.
Why does pip say it is required to install pyproject.toml-based projects?
Modern packaging no longer falls back to a deprecated setup.py install when the wheel build fails. The project has to produce a wheel, so a compile error becomes a hard install error.
How do I stop pip compiling and just use a binary?
Upgrade pip, then install a version that publishes a wheel for your tag. python -m pip install PACKAGE --only-binary=:all: refuses to compile and fails immediately if no wheel exists.
Why does this happen on Alpine Docker images but not on my laptop?
Alpine uses musl libc. Most published Linux wheels are manylinux (glibc), so pip compiles on Alpine. Switch to a Debian slim image, or install Alpine’s build-base and the matching -dev libraries.
Is this the same as metadata-generation-failed?
No. That error happens earlier, while pip is asking the project for its name and dependencies. Failed building wheel is the compile step after that succeeded.
The log says Microsoft Visual C++ 14.0 is required. Is that this error?
Yes — it is the Windows wording of the same situation. See the dedicated page: Microsoft Visual C++ 14.0 or greater is required.
Published .