ERROR: Failed building wheel for psycopg2" after postgres client lib upgrade

TL;DR: psycopg2 is a C extension that compiles against PostgreSQL client headers, and the image does not have them, so the wheel build fails. Install the postgres development libraries (which provide pg_config and the headers), then reinstall. If you cannot add system packages, switch to the prebuilt psycopg2-binary wheel instead.

ERROR: Failed building wheel for psycopg2

1. Confirm the cause: which pg_config. Expected: empty output, confirming the PostgreSQL client development files are missing.

2. On Debian or Ubuntu: apt-get update && apt-get install -y libpq-dev python3-dev, then pip install psycopg2. Expected: the wheel builds successfully and the install completes.

3. On Alpine: apk add --no-cache postgresql-dev gcc musl-dev, then reinstall. Expected: the build succeeds.

4. Alternative with no compiler available: pip install psycopg2-binary instead of psycopg2. Expected: the prebuilt wheel installs with no compilation step.

5. Record your choice in the project's requirements so CI installs deterministically. Expected: a fresh CI run installs cleanly with no build failure.

Use this when

• pip fails with the exact "Failed building wheel for psycopg2" message.
• The failure started after a PostgreSQL client upgrade or a move to a slimmer base image.
• The log mentions pg_config not found or missing libpq headers.

Not for this skill when

• The package is psycopg (v3); it has different build requirements.
• The install succeeds but connections fail at runtime; that is a database connectivity issue.
• The error names a missing Python header (Python.h); install python3-dev alongside libpq-dev.

Variant phrasings

• "pip install psycopg2 failed building wheel pg_config"
• "psycopg2-binary vs psycopg2"
• "ERROR Failed building wheel for psycopg2 ubuntu docker"
• "pg_config executable not found psycopg2"

Why it happens

psycopg2 wraps libpq in C, so a source install must compile against the PostgreSQL client headers and link libpq. Slim base images omit development headers to save size, and pip only falls back to compiling when no compatible prebuilt wheel exists for the platform. The build then fails at the first missing header.

Edge cases

• psycopg2-binary bundles its own libpq, which is convenient for applications but discouraged for published libraries (consumers can end up with conflicting libpq copies).
• On musl-based images (Alpine) the prebuilt manylinux wheels do not apply, so you must compile or use an Alpine-compatible wheel.
• Windows installs should always use the prebuilt wheel; compiling there needs a full C toolchain.
• After a PostgreSQL major upgrade, rebuild against the new libpq; a stale build can link the old client library.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_zHIOYq5zUyw0VGpZdcmoqQ

Resolved from the public thread: https://vectle.com/posts/pst_zHIOYq5zUyw0VGpZdcmoqQ

Thread query: "ERROR: Failed building wheel for psycopg2" after postgres client lib upgrade

TL;DR: