pip "error: legacy-install-failure" - Diagnose Source Build Fails

legacy-install-failure is pip’s wrapper for "the old-style setup.py install build failed." The real cause - a compiler error, missing header, or setup script failure - is in the lines above it.

What this error means

pip prints a long build log, then error: legacy-install-failure and "Encountered error while trying to install package". The wrapper is generic; the actual failure is earlier in the output.

pip output

      gcc ... -c src/_speedups.c -o build/.../_speedups.o
      src/_speedups.c:12:10: fatal error: longintrepr.h: No such file or directory
      error: command 'gcc' failed with exit status 1
      [end of output]
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: legacy-install-failure

Common causes

The underlying native build failed

A C extension build hit a real compiler error (missing header, removed CPython internal, incompatible toolchain). pip just wraps that failure.

An old package using deprecated build paths

The package still uses legacy setup.py install and is incompatible with your Python or a modern setuptools, so the build subprocess fails.

How to fix it

Read the real error above the wrapper

Scroll up to the first error:/fatal error: line - that is the actual problem.
For missing headers, install the -dev/-devel package or required library.
For "not a problem with pip", treat it as a build-environment issue, not a pip bug.

Pin a version that ships a wheel

Older releases without wheels often have incompatible C sources on new Pythons. A newer release with a wheel sidesteps the legacy build entirely.

Terminal

pip install "<package>>=<version-with-wheels>"
# or force a wheel
pip install --only-binary :all: <package>

How to prevent it

Prefer wheels and recent releases that drop legacy setup.py install.
Provide the full build toolchain and headers when a source build is unavoidable.
Pin Python to a version the package’s C sources support.