pip psycopg2 "Error: pg_config executable not found" in CI

By Daniel Zoghalchali·Latchkey

Building psycopg2 from source runs pg_config to locate the PostgreSQL client library. Without the Postgres client development package, pg_config is not on PATH and the build stops immediately.

What this error means

Installing psycopg2 fails early with Error: pg_config executable not found. and a hint to add it to PATH or install the Postgres dev package. The binary variant psycopg2-binary does not hit this, since it ships a prebuilt wheel.

pip output

    Error: pg_config executable not found.

    pg_config is required to build psycopg2 from source.  Please add the directory
    containing pg_config to the $PATH or specify the full executable path ...
ERROR: Could not build wheels for psycopg2

Common causes

PostgreSQL client dev package not installed

pg_config ships with libpq-dev (Debian/Ubuntu) or postgresql-devel (RHEL). Without it the source build cannot locate libpq and fails.

Building the source variant instead of the binary

The psycopg2 distribution builds from source; psycopg2-binary is a self-contained wheel. Installing the former on a runner without libpq triggers this.

How to fix it

Use psycopg2-binary in CI

The binary wheel needs no compiler, no libpq-dev, and no pg_config - ideal for CI and dev.

Terminal

pip install psycopg2-binary   # instead of psycopg2

Install the Postgres client dev package for source builds

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y build-essential python3-dev libpq-dev
pip install psycopg2

How to prevent it

Prefer psycopg2-binary in CI to avoid the source build.
Bake libpq-dev into images that build psycopg2 from source.
Keep the choice of variant consistent across dev and CI.

Frequently asked questions

What causes ""pg_config executable not found""?

pg_config ships with libpq-dev (Debian/Ubuntu) or postgresql-devel (RHEL). Without it the source build cannot locate libpq and fails.

How do I fix "pg_config executable not found"?