SOLVED: error: pg_config executable not found

The error "pg_config executable not found" appears when you try to install psycopg2 (the Python PostgreSQL adapter) via pip and your system does not have the PostgreSQL C development headers installed. This guide explains the cause and provides a fix for every major platform.

The Full Error Message

$ pip install psycopg2
Collecting psycopg2
  Downloading psycopg2-2.9.9.tar.gz (384 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: psycopg2
  Building wheel for psycopg2 (pyproject.toml) ... error
  error: subprocess-exited-with-error

  × Building wheel for psycopg2 (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [23 lines of 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 with the
      python setup.py build_ext --pg-config /path/to/pg_config build ...

      If you prefer to avoid building psycopg2 from source, please install the PyPI
      'psycopg2-binary' package instead.
      ...

Why This Happens

psycopg2 is a C extension that wraps libpq, the PostgreSQL client library. When pip builds psycopg2 from source, it calls pg_config — a utility that ships with the PostgreSQL development headers — to find the correct include paths and library locations for compilation.

If pg_config is not on your PATH, the build fails immediately. This usually means:

• The PostgreSQL development package (libpq-dev, postgresql-devel, etc.) is not installed.
• PostgreSQL is installed but the development headers package is separate and was not included.
• You are inside a minimal Docker/container image that only has the PostgreSQL runtime, not the dev headers.

Fix 1: Ubuntu and Debian

Install the PostgreSQL development headers and Python development headers:

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

Then retry the install:

pip install psycopg2

libpq-dev provides pg_config and the libpq headers. python3-dev provides the Python C API headers required to build any C extension.

Fix 2: Fedora, RHEL, CentOS, Rocky Linux

sudo dnf install -y postgresql-devel python3-devel

On older CentOS/RHEL systems using yum:

sudo yum install -y postgresql-devel python3-devel

Then retry:

pip install psycopg2

Fix 3: macOS (Homebrew)

brew install postgresql

Homebrew installs pg_config into its prefix. If pip still cannot find it, add the Homebrew bin directory to your PATH:

export PATH=$(brew --prefix postgresql)/bin:$PATH
pip install psycopg2

To make the PATH change permanent, add the export line to ~/.zshrc or ~/.bash_profile.

If you have multiple PostgreSQL versions installed via Homebrew (e.g. postgresql@14 and postgresql@16), specify the one you want:

export PATH=$(brew --prefix postgresql@16)/bin:$PATH
pip install psycopg2

Fix 4: Alpine Linux (Docker)

Alpine uses musl libc instead of glibc, so both the PostgreSQL dev package and the musl C headers are required:

apk add --no-cache postgresql-dev musl-dev gcc python3-dev

Then:

pip install psycopg2

This is particularly relevant for slim Python Docker images (python:3.x-alpine). A typical Dockerfile pattern:

FROM python:3.12-alpine

RUN apk add --no-cache postgresql-dev musl-dev gcc python3-dev

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

Fix 5: Use psycopg2-binary (Simplest Option)

If you do not need to compile from source and just want a working PostgreSQL driver quickly, install the pre-compiled binary wheel instead:

pip install psycopg2-binary

psycopg2-binary bundles libpq statically and does not require any system packages. No pg_config, no compiler, no headers.

When to use psycopg2-binary

• Local development environments
• Docker images where you want to minimize dependencies
• CI pipelines where build speed matters
• Any environment where you cannot install system packages

When to use psycopg2 (from source)

The psycopg2 maintainers recommend against using psycopg2-binary in production because:

• The bundled libpq may not receive OS-level security patches automatically.
• It may conflict with other system libraries that also link against libpq.
• The binary wheel is compiled against a specific libpq version and may not work optimally with your PostgreSQL server version.

For production deployments, install the system dev headers and build from source.

Verifying pg_config is Available

After installing the dev package, confirm pg_config is on your PATH:

which pg_config
pg_config --version

Expected output:

/usr/bin/pg_config
PostgreSQL 16.2

If which pg_config returns nothing, the dev package did not install correctly or the binary is in a non-standard location. Find it manually:

find /usr -name pg_config 2>/dev/null

Then add that directory to your PATH before running pip:

export PATH=/path/to/directory:$PATH
pip install psycopg2

Quick Recommendation Table

Related Articles

• Fix: gpg signing failed: inappropriate ioctl for device
• Fix: function main is undeclared in the main package
• Using Go with PostgreSQL