Python Psycopg2: How to Resolve "pg_config executable not found" in Python

When working with PostgreSQL databases in Python, the psycopg2 library is the most widely used adapter for database interaction. However, during installation, you may encounter a frustrating error that stops the process entirely:

Error: pg_config executable not found.

This error occurs when pip attempts to compile psycopg2 from source but cannot locate the pg_config executable: a utility that provides the compiler and linker flags needed to build C extensions against the PostgreSQL client library.

In this guide, you'll learn exactly why this error happens and how to fix it on Windows, Linux (Debian/Ubuntu, RHEL/CentOS/Fedora), and macOS.

Why Does This Error Occur?

The psycopg2 package contains C extensions that must be compiled against the PostgreSQL client library. During the build process, the setup script calls pg_config to discover the location of PostgreSQL headers, libraries, and configuration details. If pg_config is missing or not accessible, the build fails immediately.

The most common root causes are:

• PostgreSQL is not installed on your system at all.
• PostgreSQL development headers are missing: pg_config ships with the development package, not the base server or client.
• pg_config is not on your system's PATH: the binary exists but Python's build tools can't find it.
• You're installing psycopg2 (source version) instead of the precompiled psycopg2-binary.

Quick Diagnosis

Before applying any fix, check whether pg_config is installed and accessible.

On Linux / macOS:

which pg_config

On Windows (Command Prompt):

where pg_config

• If a path is returned, pg_config exists. The issue is likely a PATH configuration problem.
• If nothing is returned, the PostgreSQL development package is not installed.

Fixing the Error on Linux (Debian / Ubuntu)

Step 1: Install PostgreSQL Development Headers

The pg_config binary is included in the libpq-dev package, not in the base postgresql package:

sudo apt-get update
sudo apt-get install libpq-dev python3-dev build-essential

Step 2: Verify pg_config Is Accessible

which pg_config

Expected output:

/usr/bin/pg_config

Step 3: Install psycopg2

pip install psycopg2

Alternative: Skip Compilation Entirely

pip install psycopg2-binary

Fixing the Error on Linux (RHEL / CentOS / Fedora)

Step 1: Install Development Libraries

RHEL / CentOS:

sudo yum install postgresql-devel python3-devel gcc

Fedora:

sudo dnf install postgresql-devel python3-devel gcc

Step 2: Verify and Install

which pg_config
pip install psycopg2

Fixing the Error on macOS

Step 1: Install PostgreSQL Using Homebrew

brew install postgresql

This installs both the PostgreSQL server and the pg_config utility.

Step 2: Verify the pg_config Path

which pg_config

Expected output (Apple Silicon):

/opt/homebrew/bin/pg_config

Expected output (Intel Mac):

/usr/local/bin/pg_config

Step 3: Add pg_config to PATH (If Not Found)

If which pg_config returns nothing even after installing PostgreSQL via Homebrew, add it to your shell profile manually:

echo 'export PATH="/opt/homebrew/opt/postgresql/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

echo 'export PATH="/opt/homebrew/opt/postgresql/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Step 4: Install psycopg2

pip install psycopg2

Alternative: Skip Compilation

pip install psycopg2-binary

Fixing the Error on Windows

Step 1: Install PostgreSQL

Download the installer from the official site: https://www.postgresql.org/download/windows/

During installation, make sure the Command Line Tools (or Development Tools) option is selected.

Step 2: Add pg_config.exe to Your PATH

Locate pg_config.exe. It is typically found at:

C:\Program Files\PostgreSQL\16\bin\pg_config.exe

Add the bin directory to your system PATH:

setx PATH "%PATH%;C:\Program Files\PostgreSQL\16\bin"

Step 3: Install psycopg2

pip install psycopg2

Alternative: Skip Compilation

pip install psycopg2-binary

This is often the most reliable approach on Windows, as setting up a C compiler toolchain can be complex.

psycopg2 vs. psycopg2-binary: Which Should You Use?

Verifying the Installation

After a successful install, verify that psycopg2 works correctly with a simple connection test:

import psycopg2

try:
    connection = psycopg2.connect(
        host="127.0.0.1",
        port="5432",
        database="your_database",
        user="your_username",
        password="your_password",
    )
    print("Connection successful!")

    cursor = connection.cursor()
    cursor.execute("SELECT version();")
    version = cursor.fetchone()
    print(f"PostgreSQL version: {version[0]}")

except psycopg2.Error as err:
    print(f"Error: {err}")

finally:
    if "connection" in locals() and connection and not connection.closed:
        cursor.close()
        connection.close()
        print("Connection closed.")

Output:

Connection successful!
PostgreSQL version: PostgreSQL 16.3 on x86_64-pc-linux-gnu, compiled by gcc ...
Connection closed.

Best Practice: Use Virtual Environments

Always isolate your project dependencies in a virtual environment to avoid conflicts with system packages:

python -m venv myenv
source myenv/bin/activate        # On Windows: myenv\Scripts\activate
pip install psycopg2             # or psycopg2-binary

Quick Reference Table

Conclusion

The "pg_config executable not found" error in Python occurs because the psycopg2 build process needs the pg_config utility to locate PostgreSQL headers and libraries. The fix depends on your operating system but always comes down to one of two approaches:

1. Install the PostgreSQL development package (libpq-dev, postgresql-devel, or brew install postgresql) so that pg_config is available for source compilation.
2. Use psycopg2-binary to skip compilation entirely with a self-contained, precompiled package.

For most development workflows, pip install psycopg2-binary is the fastest path forward. For production deployments where you want your application to use system-managed PostgreSQL libraries, install the proper development headers and compile from source.