How to Fix - "pg_config executable not found" in Python

When working with PostgreSQL databases in Python, the psycopg2 library is a popular choice for database interaction. However, while installing or using psycopg2, you might encounter the error:

"pg_config executable not found"

This error occurs when Python's package installer (pip) tries to compile the psycopg2 package but can't locate the pg_config executable, which is necessary to find PostgreSQL headers and libraries.

Why does this error occur?

Let’s understand some of the possible causes that could lead to this error. These are a few common scenarios where things might go wrong and trigger this issue.

• PostgreSQL is not installed on your system.
• pg_config is not in your system's PATH.
• You're trying to install psycopg2 (source version) and it requires compilation.
• You're on Windows and PostgreSQL binaries are not configured properly.
• Missing development packages required for compilation (mostly on Linux).

Solutions for different operating system

Depending on your operating system, the steps to resolve the "pg_config executable not found" error can vary. Below are platform-specific solutions to help you fix it quickly.

For Windows

Let’s follow these steps to solve the issue on a Windows system.

Step 1: Install PostgreSQL

• Download from the official site: https://www.postgresql.org/download/windows/
• During setup, ensure that the “Development Tools” option is selected.

Step 2: Add pg_config to PATH

• Locate pg_config.exe, usually here:

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

• Add the bin folder to the system PATH:

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

Step 3: Install psycopg2

pip install psycopg2

Step 4: Alternative (Skip Compilation)

pip install psycopg2-binary

This version includes precompiled binaries and doesn't need pg_config.

For Linux

Let’s follow these steps to fix the “pg_config executable not found” error on a Linux system.

Step 1: Install PostgreSQL and Development Headers

sudo apt update

sudo apt install postgresql postgresql-contrib libpq-dev python3-dev

Step 2: Install psycopg2

pip install psycopg2

Step 3: Alternative (No Compilation Needed)

pip install psycopg2-binary

For macOS

Here’s how to resolve the issue on macOS, especially for users using Homebrew.

Step 1: Install PostgreSQL using Homebrew

brew install postgresql

Step 2: Check pg_config Path

which pg_config

Example output:

/opt/homebrew/bin/pg_config

Step 3: Add pg_config to PATH (if not already there)

• Add the following to your shell profile (e.g., ~/.zshrc or ~/.bash_profile):

export PATH="/opt/homebrew/opt/postgresql/bin:$PATH"

• Then reload:

source ~/.zshrc # or source ~/.bash_profile

Step 4: Install psycopg2

pip install psycopg2

Step 5: Alternative (Skip Compilation)

pip install psycopg2-binary