# pip "Failed building wheel for ..." - Fix Wheel Build Failures

> Fix pip "ERROR: Failed building wheel for <pkg>" in CI - when there is no prebuilt wheel and the source build fails for lack of a compiler or headers.

Source: https://latchkey.dev/learn/python/pip-could-not-build-wheels  
Updated: 2026-06-25

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.

## 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
```

> Compatible tags decide whether a wheel is usable. A package that installs from a wheel on your machine and builds from source in CI is a tag mismatch, and the resulting failure is a compiler error rather than a pip error.

## FAQ

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt