Skip to main content

Python Psycog2: 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.
The Fastest Fix for Any Platform

If you don't need to compile from source and just want things to work, install the precompiled binary version:

pip install psycopg2-binary

This package includes all required PostgreSQL client libraries and does not need pg_config. It's ideal for development, testing, and many production scenarios.

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
info

If you also need the PostgreSQL server itself (not just the client libraries), add it explicitly:

sudo apt-get install postgresql postgresql-contrib

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:

# For zsh (default on modern macOS):
echo 'export PATH="/opt/homebrew/opt/postgresql/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash:
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"
warning

After running setx, you must close and reopen your terminal for the change to take effect. The setx command modifies the registry but does not update the current session.

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?​

Featurepsycopg2psycopg2-binary
Requires pg_configYesNo
Requires C compilerYesNo
Includes bundled librariesNo (links to system libpq)Yes (self-contained)
Recommended for production✅ (by psycopg2 maintainers)Acceptable for most cases
Best for development/CIWorks but harder to set up✅ Easy, no dependencies
info

The psycopg2 maintainers recommend using the source distribution (psycopg2) in production because psycopg2-binary bundles its own copy of libpq and libssl, which may not receive system security updates. For development, testing, and CI/CD pipelines, psycopg2-binary is perfectly fine.

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​

Operating SystemInstall Dev LibrariesSkip Compilation
Ubuntu / Debiansudo apt-get install libpq-dev python3-dev build-essentialpip install psycopg2-binary
RHEL / CentOSsudo yum install postgresql-devel python3-devel gccpip install psycopg2-binary
Fedorasudo dnf install postgresql-devel python3-devel gccpip install psycopg2-binary
macOS (Homebrew)brew install postgresqlpip install psycopg2-binary
WindowsInstall PostgreSQL with CLI tools, add bin to PATHpip install psycopg2-binary

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.

Table of Contents