Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

pip: failed building wheel and subprocess-exited-with-error

pip tried to compile because no wheel matched. Find the wheel, switch to a binary variant, or install the build dependencies.

~5 min readPython
#Python#pip#Docker#Packaging
A python wheel crate on a bench missing its compiler tool beside an amber error plate

Introduction & Quick Summary

pip install ends with:

code
error: subprocess-exited-with-error × Building wheel for psycopg2 (pyproject.toml) did not run successfully. │ exit code: 1 ╰─> [18 lines of output] .../psycopg/config.h:1:10: fatal error: libpq-fe.h: No such file or directory [end of output] note: This error originates from a subprocess, and is likely not a problem with pip.

The note is accurate and unhelpful at the same time. pip is not broken: it found no prebuilt wheel for your interpreter, platform and ABI, so it unpacked the source distribution and ran the package's build backend. That build needs a C compiler and system headers, and this machine has neither.

The three questions that resolve it, in order:

  1. Does a wheel exist for this exact environment? If yes, pip should have used it - fix the interpreter version, platform tag, or index, and the compile disappears.
  2. Is the package one that should be installed as a binary variant? psycopg2-binary instead of psycopg2, psycopg[binary] instead of psycopg, mysqlclient versus PyMySQL.
  3. If it must compile, are the build dependencies present? Compiler, Python headers, and the C library the package links against (libpq-dev, libssl-dev, libffi-dev), or a Rust toolchain for the growing set of Rust-backed packages.

Installing build-essential blindly "works" often enough to become folklore, and it still fails for Rust-backed builds and for musl images.

Core Mechanics, Signatures & Reproducible Setup

pip resolves a requirement against the available distributions: wheels first, sorted by compatibility with the interpreter's ABI tag and the platform's manylinux level, then the sdist. When only an sdist is usable, pip creates an isolated build environment from build-system.requires in pyproject.toml, runs the backend's build_wheel, and installs the result. Everything printed between the ╰─> marker and [end of output] is the build log, and the first real error is usually the last fatal error: or error: line before it.

bash
python -V pip -V python -c "import sysconfig; print(sysconfig.get_platform(), sysconfig.get_config_var('SOABI'))" pip debug --verbose | grep -i manylinux | head # tags this interpreter accepts
bash
# see whether a wheel exists at all, before changing anything pip download --only-binary=:all: --no-deps psycopg2 -d /tmp/w # ERROR: Could not find a version that satisfies the requirement psycopg2 # (from versions: none) -> no wheel for this platform/ABI pip download --only-binary=:all: --no-deps --platform manylinux2014_x86_64 \ --python-version 3.13 --implementation cp psycopg2-binary -d /tmp/w

The second command answers the question for a different target than the machine you are on, which is how you check a CI image from a laptop.

Key Comparison Table

Error line in the build logMissing pieceInstall
Python.h: No such file or directoryPython development headerspython3-dev or python3.13-dev
command 'gcc' failedC compilerbuild-essential / gcc
libpq-fe.h: No such file or directoryPostgreSQL client headerslibpq-dev
openssl/opensslv.h: No such file or directoryOpenSSL headerslibssl-dev
ffi.h: No such file or directorylibffi headerslibffi-dev
can't find Rust compilerRust toolchainrustup or a newer package version
pg_config executable not foundPostgreSQL dev packagelibpq-dev
No module named 'mesonpy'build backend in isolationusually a pip upgrade
ApproachSpeedWorks on muslMaintenance
Binary wheel packagefastestyesnone
Build in a full image with dev packagesslowyesimage size
Multi-stage build, copy site-packagesmediumyesmedium
--no-build-isolation with preinstalled depsfast after setupyesfragile

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Prefer the binary distribution when one exists

Some packages ship a compiled variant under a different name for exactly this reason. Using it is not a shortcut; it is the supported distribution for deployment:

bash
pip install "psycopg[binary]" # psycopg 3, bundled libpq pip install psycopg2-binary # psycopg 2, bundled libpq pip install "mysqlclient" # needs headers pip install PyMySQL # pure Python alternative

Check the project's documentation for which variant it recommends in containers; several projects explicitly advise against the -binary variant only for production builds on the same OS, not for a Docker image.

2. Fixing pip so it can see the wheel

pip only understands wheel tags introduced after its own release. manylinux_2_28 and newer macOS tags need a recent pip, and an old pip silently falls back to the sdist:

bash
python -m pip install --upgrade "pip>=24.2" setuptools wheel python -m pip install --only-binary=:all: psycopg2-binary

--only-binary=:all: is the honest test: it either installs a wheel or tells you there is none, instead of spending minutes compiling.

3. A Dockerfile that builds once and ships small

Install the toolchain in a builder stage and copy the built site-packages into the runtime image, so compilers never reach production:

dockerfile
FROM python:3.13-bookworm AS build RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential libpq-dev libssl-dev libffi-dev curl \ && curl https://sh.rustup.rs -sSf | sh -s -- -y --profile minimal ENV PATH="/root/.cargo/bin:$PATH" RUN python -m venv /opt/venv COPY requirements.txt . RUN /opt/venv/bin/pip install --upgrade pip && /opt/venv/bin/pip install -r requirements.txt FROM python:3.13-bookworm-slim COPY --from=build /opt/venv /opt/venv ENV PATH="/opt/venv/bin:$PATH"

On -slim images, libpq-dev is not present at runtime; a package that linked against it needs the runtime library libpq5 instead. Check with ldd on the compiled extension.

4. musl versus glibc

python:3.13-alpine uses musl, and most projects publish manylinux wheels only. Every package then compiles from source, which is why an Alpine image needs a much larger build toolchain. Two honest options:

dockerfile
# keep alpine and pay the build cost RUN apk add --no-cache build-base libffi-dev openssl-dev postgresql-dev # or use a glibc slim image and get wheels FROM python:3.13-slim

Mixing is worse than either: a wheel built for glibc will not import on musl, and the error (Error loading shared library) appears at runtime, long after the install succeeded.

5. Rust-backed packages

pydantic-core, cryptography (recent versions), orjson, tokenizers and uvloop compile Rust code when no wheel is available. The log says error: can't find Rust compiler or this version of Cargo is older than the 2024 edition, and installing build-essential does nothing:

curl https://sh.rustup.rs -sSf | sh -s -- -y --profile minimal export PATH="$HOME/.cargo/bin:$PATH" python -m pip install --only-binary=:all: cryptography # try the wheel first

Prefer a newer pip and a supported Python version over adding Rust: the wheels exist for current CPython releases on common platforms, and the source build is the fallback.

6. Finding out which wheel you should have gotten

The PyPI JSON API lists every distribution file for a release with its filename, which encodes the platform and ABI tags. Query it before assuming a wheel is missing:

curl -s https://pypi.org/pypi/psycopg2-binary/json \ | python -c "import json,sys; d=json.load(sys.stdin); print('\n'.join(u['filename'] for u in d['urls']))"

cp313-manylinux_2_17_x86_64 tells you the wheel exists for CPython 3.13 on glibc x86_64; the absence of a cp313 file means the project has not built for that interpreter yet. Paste the same JSON into JSON Formatter to filter by tag without writing a script, and use HTTP header inspector when a private index returns a 403 that looks like a missing package.

Common Compilation/Runtime Mistakes & Version Gotchas

  • --no-build-isolation as a fix. It reuses the current environment, which can then fail on a missing build backend rather than a missing compiler.
  • Installing python3-dev without matching the interpreter. python3.13 needs python3.13-dev on Debian-derived images; the default package may target another minor version.
  • A requirements.txt pin that predates wheels for the current Python. Upgrading the pin is often cheaper than installing a toolchain.
  • Compiling on a laptop and copying the venv into an image. Native extensions are tied to the build libc; the import fails at runtime.
  • --pre to work around a missing stable wheel. It installs betas of the whole dependency tree.
  • Root installs into the system Python. pip install as root outside a venv overwrites distribution files; use a venv or --user.
  • Ignoring the [end of output] marker. The real error is the last fatal error before it; the lines above are usually harmless warnings from a configure step.

Primary references: pip install documents --only-binary, build isolation and the environment variables that control it, and PyPI's file format help explains what the wheel filename tags mean.

Official references

primary documentation

The Python documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.