pip "Failed building wheel for ..." - Fix Wheel Build Failures
By Daniel Zoghalchali·Latchkey
pip could not download a prebuilt wheel for this package and tried to compile it from source - and that compile failed, usually for a missing compiler or system header.
What this error means
During install pip prints "Building wheel for <pkg> ... error" followed by a compiler error, then "Failed building wheel for <pkg>" and finally "Could not build wheels for <pkg>". The failure is in the native build, not in pip itself.
pip output
Building wheel for psycopg2 (pyproject.toml) ... error
error: command 'gcc' failed: No such file or directory
ERROR: Failed building wheel for psycopg2
ERROR: Could not build wheels for psycopg2, which is required to install
pyproject.toml-based projects
Diagnose it: which Python, and which index?
A pip failure in CI is usually about the interpreter or the index rather than the package. Runners have several Pythons installed, and the one on PATH is not necessarily the one your virtualenv or your workflow selected.
Terminal
which -a python python3 pip pip3
python -c "import sys; print(sys.executable, sys.version)"
pip config list
pip debug --verbose 2>/dev/null | grep -i "compatible tags" | head -5
Common causes
No prebuilt wheel for this platform/Python
When PyPI has no compatible wheel, pip falls back to building from the sdist. That needs a working build toolchain the runner may not have.
Missing compiler or development headers
The source build needs gcc/clang plus library headers (e.g. libpq-dev for psycopg2, python3-dev for the Python headers). On a slim image those are absent.
How to fix it
Prefer a binary wheel where one exists
Many packages ship a pure-binary variant that needs no compiler. For psycopg2, psycopg2-binary avoids the build entirely.
Terminal
pip install psycopg2-binary # instead of psycopg2
Install the build toolchain and headers
If you must build from source, add the compiler and the package’s dev headers before installing.
Check pip index versions <pkg> for releases with wheels for your Python.
If a newer Python has no wheel yet, pin CI to a supported Python version.
Only fall back to a source build when no compatible wheel exists.
How to prevent it
Prefer wheels and -binary variants in CI to avoid compiling.
If you build from source, bake the toolchain and headers into the runner image.
Pin Python to a version with full wheel coverage for your dependencies.
Frequently asked questions
What causes pip "Failed building wheel for ..."?
There are 2 common causes: no prebuilt wheel for this platform/python and missing compiler or development headers. When PyPI has no compatible wheel, pip falls back to building from the sdist.
How do I fix pip "Failed building wheel for ..."?
There are 3 fixes depending on which cause you have: prefer a binary wheel where one exists, install the build toolchain and headers, and pin to a version that ships a wheel. Work through them in order, since the first is the most common.
What does pip "Failed building wheel for ..." actually mean?
During install pip prints "Building wheel for <pkg> ...
How do I stop pip "Failed building wheel for ..." happening again?
Prefer wheels and -binary variants in CI to avoid compiling. The prevention section lists 3 changes that keep it from recurring.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
