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.

Introduction & Quick Summary
pip install ends with:
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:
- 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.
- Is the package one that should be installed as a binary variant?
psycopg2-binaryinstead ofpsycopg2,psycopg[binary]instead ofpsycopg,mysqlclientversusPyMySQL. - 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.
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# 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/wThe 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 log | Missing piece | Install |
|---|---|---|
| Python.h: No such file or directory | Python development headers | python3-dev or python3.13-dev |
| command 'gcc' failed | C compiler | build-essential / gcc |
| libpq-fe.h: No such file or directory | PostgreSQL client headers | libpq-dev |
| openssl/opensslv.h: No such file or directory | OpenSSL headers | libssl-dev |
| ffi.h: No such file or directory | libffi headers | libffi-dev |
| can't find Rust compiler | Rust toolchain | rustup or a newer package version |
| pg_config executable not found | PostgreSQL dev package | libpq-dev |
| No module named 'mesonpy' | build backend in isolation | usually a pip upgrade |
| Approach | Speed | Works on musl | Maintenance |
|---|---|---|---|
| Binary wheel package | fastest | yes | none |
| Build in a full image with dev packages | slow | yes | image size |
| Multi-stage build, copy site-packages | medium | yes | medium |
--no-build-isolation with preinstalled deps | fast after setup | yes | fragile |
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:
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 alternativeCheck 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:
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:
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 /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:
# 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-slimMixing 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 firstPrefer 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-isolationas a fix. It reuses the current environment, which can then fail on a missing build backend rather than a missing compiler.- Installing
python3-devwithout matching the interpreter.python3.13needspython3.13-devon Debian-derived images; the default package may target another minor version. - A
requirements.txtpin 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.
--preto work around a missing stable wheel. It installs betas of the whole dependency tree.- Root installs into the system Python.
pip installas root outside a venv overwrites distribution files; use a venv or--user. - Ignoring the
[end of output]marker. The real error is the lastfatal errorbefore 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 documentationThe Python documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesasyncpg DuplicatePreparedStatement on PgBouncer and Supabase
asyncpg caches prepared statements per connection while a transaction pooler rotates connections underneath it. The cache setting, pool sizing and retry that fix it.
Python Tabulate: Markdown Grid Headers and Alignment
Use Python's tabulate library to format Markdown tables, set custom headers, and control column alignment with pipe and grid formats.
Using pytest.mark.parametrize for Parameterized Tests in Python
Learn how to use pytest.mark.parametrize to write parameterized tests in Python. Covers syntax, multiple arguments, fixtures, custom IDs, class/module-level use, and common pitfalls.
Django select_related and prefetch_related: Fix N+1 Queries
Learn how to eliminate N+1 queries in Django with select_related and prefetch_related, including practical examples, when to use each, and common pitfalls.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.