Django "Error: pg_config executable not found" installing psycopg2 in CI

The source build of psycopg2 needs pg_config from the Postgres client dev package to compile against libpq. A slim runner image lacks libpq-dev, so the build fails before the Django driver installs.

What this error means

pip install of psycopg2 (a Django Postgres dependency) fails with "Error: pg_config executable not found." during the build step.

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: could not build wheels for psycopg2

Common causes

libpq-dev is not installed on the runner

Building psycopg2 from source needs pg_config and libpq headers; a minimal image omits them.

The source distribution was chosen over a binary wheel

Requirements pin psycopg2 (source) instead of psycopg2-binary, forcing a compile that needs the dev toolchain.

How to fix it

Install the Postgres client dev package

Provide libpq-dev (and a compiler) before pip so pg_config is on PATH.

sudo apt-get update
sudo apt-get install -y libpq-dev gcc

Use the prebuilt binary package for CI

psycopg2-binary ships wheels and needs no compiler, which is fine for tests.

pip install psycopg2-binary

How to prevent it

• Install libpq-dev and gcc before pip when building psycopg2 from source.
• Prefer psycopg2-binary in CI to skip the native build.
• Bake the Postgres client headers into a custom runner image.

Related guides