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

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.

      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

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

1. Scroll up to the first error: or fatal error: line inside the build log.
2. Install whatever it names - a compiler, a -dev package, or a build dependency.
3. 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.

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.

Related guides