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

Building psycopg2 from source requires pg_config (shipped by the PostgreSQL client dev package) to locate libpq headers. It is not on PATH, so the build cannot configure the extension.

What this error means

pip fails building psycopg2 with "Error: pg_config executable not found." and a hint to add it to PATH or install libpq-dev.

    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
    error: subprocess-exited-with-error

Common causes

PostgreSQL client headers are not installed

pg_config ships in libpq-dev / postgresql-devel; without it psycopg2's source build cannot find libpq.

Building the source distribution instead of the binary

Installing psycopg2 compiles from source; psycopg2-binary ships a prebuilt wheel that needs no pg_config.

How to fix it

Use the binary distribution

1. Switch the requirement from psycopg2 to psycopg2-binary.
2. Re-run the install; no PostgreSQL headers are needed.

pip install "psycopg2-binary==2.9.9"

Install libpq-dev if you must build from source

Production deployments sometimes prefer the source build; install the client dev package so pg_config is present.

sudo apt-get install -y libpq-dev
# or: sudo dnf install -y postgresql-devel

How to prevent it

• Use psycopg2-binary in CI unless a source build is specifically required.
• Install libpq-dev before compiling psycopg2 from source.
• Keep the requirement name consistent across local and CI environments.

Related guides