pip "Could not build wheels for cffi" - Missing libffi & Compiler
By Daniel Zoghalchali·Latchkey
cffi compiles a small C extension against libffi. When no wheel matches and the runner has neither a compiler nor the libffi headers, the source build fails on a missing ffi.h.
What this error means
Installing cffi (often pulled in by cryptography, bcrypt, or argon2) fails with fatal error: ffi.h: No such file or directory followed by "Could not build wheels for cffi". The package installed fine elsewhere where libffi-dev was present.
pip output
c/_cffi_backend.c:15:10: fatal error: ffi.h: No such file or directory
15 | #include <ffi.h>
| ^~~~~~~
compilation terminated.
ERROR: Could not build wheels for cffi, 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
libffi development headers missing
cffi’s C backend includes ffi.h, provided by libffi-dev/libffi-devel. Without it the compile cannot find the header and aborts.
No compiler or no compatible wheel
On a slim image with no gcc, or a platform with no prebuilt cffi wheel, pip must build from source and hits the missing toolchain/headers.
How to fix it
Prefer a wheel
cffi ships wheels for mainstream platforms; upgrade pip so it picks one and skip the build.
Bake libffi-dev and a compiler into images that build from source.
Pin Python to a version with wheel coverage for cffi.
Frequently asked questions
What causes pip "Could not build wheels for cffi"?
There are 2 common causes: libffi development headers missing and no compiler or no compatible wheel. cffi’s C backend includes ffi.h, provided by libffi-dev/libffi-devel.
How do I fix pip "Could not build wheels for cffi"?
There are 2 fixes depending on which cause you have: prefer a wheel and install the compiler and libffi headers. Work through them in order, since the first is the most common.
What does pip "Could not build wheels for cffi" actually mean?
Installing cffi (often pulled in by cryptography, bcrypt, or argon2) fails with fatal error: ffi.h: No such file or directory followed by "Could not build wheels for cffi".
How do I stop pip "Could not build wheels for cffi" happening again?
Prefer wheels for cffi and its dependents in CI. 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.
