pip "Could not build wheels for X" (PEP 517) in CI

By Kaveh Alemi·Latchkey

pip ran the package's PEP 517 build backend to produce a wheel and the backend exited non-zero. The real failure - a compiler error or missing build dependency - is in the captured output above this summary line.

What this error means

pip prints a build log, then "ERROR: Could not build wheels for X, which is required to install pyproject.toml-based projects". One or more packages failed to compile from source.

pip

      gcc: error: ... : No such file or directory
      error: command '/usr/bin/gcc' failed with exit code 1
      [end of output]
ERROR: Failed building wheel for cffi
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

No prebuilt wheel, so pip compiles from source

The runner platform has no matching wheel, so pip falls back to building the sdist - which needs a working toolchain and headers that may be absent.

A missing system library or build dependency

The native build needs a compiler, dev headers, or a library (libffi, openssl) the runner image does not provide.

How to fix it

Read the captured build error first

Scroll up to the first error: or fatal error: line inside the build log.
Install whatever it names - a compiler, a -dev package, or a build dependency.
Re-run the install once the dependency is present.

Prefer a prebuilt wheel

Pin a version that publishes a wheel for the runner platform, or upgrade pip so it can find newer manylinux wheels and skip the build.

Terminal

python -m pip install --upgrade pip
pip install --only-binary=:all: cffi

How to prevent it

Prefer wheels in CI so the build backend never runs.
Install required -dev system packages before pip when a source build is unavoidable.
Keep pip current so it discovers the newest compatible wheels.

Frequently asked questions

What causes pip "Could not build wheels for X" (PEP 517) in CI?

There are 2 common causes: no prebuilt wheel, so pip compiles from source and a missing system library or build dependency. The runner platform has no matching wheel, so pip falls back to building the sdist - which needs a working toolchain and headers that may be absent.

How do I fix pip "Could not build wheels for X" (PEP 517) in CI?

There are 2 fixes depending on which cause you have: read the captured build error first and prefer a prebuilt wheel. Work through them in order, since the first is the most common.

What does pip "Could not build wheels for X" (PEP 517) in CI actually mean?

pip prints a build log, then "ERROR: Could not build wheels for X, which is required to install pyproject.toml-based projects".

How do I stop pip "Could not build wheels for X" (PEP 517) in CI happening again?

Prefer wheels in CI so the build backend never runs. The prevention section lists 3 changes that keep it from recurring.