pip "error: legacy-install-failure" in CI

pip could not build a wheel for the package and fell back to the deprecated setup.py install path, which then also failed. The legacy-install-failure line is the fallback error, not the original cause.

What this error means

pip prints "Running setup.py install for X ... error" and ends with "error: legacy-install-failure". The real failure is in the compiler or setup.py output above.

  Running setup.py install for pyzmq ... error
  error: subprocess-exited-with-error

  x Running setup.py install for pyzmq did not run successfully.
error: legacy-install-failure

Common causes

Wheel build failed, forcing the legacy path

pip prefers pip wheel; when that fails (missing compiler, missing headers) it tries setup.py install, which fails the same way and reports legacy-install-failure.

The package no longer supports setup.py install

Newer setuptools removed direct setup.py install; a package that still relies on it errors out on this path.

How to fix it

Fix the underlying wheel build

1. Read the compiler or setup.py error printed above the legacy-install-failure line.
2. Install the missing build toolchain or headers it names.
3. Re-run so pip can build a wheel and skip the legacy path entirely.

sudo apt-get update && sudo apt-get install -y build-essential
python -m pip install --upgrade pip wheel

Prefer a prebuilt wheel

Pin to a version that publishes a manylinux wheel so no local build is needed.

pip install --only-binary=:all: pyzmq

How to prevent it

• Install a C toolchain in CI before compiling source packages.
• Prefer versions that ship binary wheels for your platform.
• Keep pip and setuptools current so the modern build path is used.

Related guides