How to Resolve "Error: pg_config executable not found' when Installing psycopg2 in Python pip

When installing the psycopg2 library, a popular PostgreSQL adapter for Python, you may encounter the Error: pg_config executable not found. This error occurs because pip is attempting to install psycopg2 by compiling it from its source code. This compilation process requires system-level development tools from a local PostgreSQL installation, specifically the pg_config utility, which provides the necessary configuration for the build.

The error log itself provides the two primary solutions. This guide will walk you through both: the simple fix of installing a pre-compiled binary version, and the more advanced method of installing the required system dependencies to build from source.

Understanding the Error: Why psycopg2 Needs pg_config

psycopg2 is a C extension module, meaning parts of it are written in C for performance and to interface with PostgreSQL's C library, libpq. When you run pip install psycopg2, pip may download the source code and try to compile it on your machine.

The pg_config executable is a utility that comes with a PostgreSQL installation. It tells the compiler where to find the necessary header files (.h files) and libraries (.so or .dll files) for libpq. The error pg_config executable not found means this utility is either not installed or not available in your system's PATH environment variable.

Solution 1: Install the Pre-compiled Binary (Recommended for Most Users)

The error message itself suggests the easiest solution: using the pre-compiled binary package. This avoids the need for any local compilation or system dependencies.

Example of command causing the error:

pip install psycopg2

Solution: install the psycopg2-binary package instead of psycopg2.

pip install psycopg2-binary

This single command should resolve the error for most development and deployment scenarios.

Solution 2: Build from Source by Installing System Dependencies

If you need to build psycopg2 from source (e.g., for production use or to link against a specific PostgreSQL version), you must install the PostgreSQL development headers on your system. This will provide the pg_config utility.

On Debian / Ubuntu

Solution:

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

pip install psycopg2

On Fedora / RHEL / CentOS

Solution:

sudo dnf install postgresql-devel

pip install psycopg2

On macOS (using Homebrew)

Solution:

brew install postgresql

pip install psycopg2

On Windows

Solution:

1. Download the PostgreSQL installer from the official website.
2. Run the installer. During the installation, make sure you install all components.
3. After installation, find the bin directory of your PostgreSQL installation (e.g., C:\Program Files\PostgreSQL\14\bin).
4. Add this directory to your system's PATH environment variable.
5. Restart your terminal or command prompt for the PATH change to take effect.
6. Now, the original pip install psycopg2 command will succeed.

Conclusion

For the vast majority of users, pip install psycopg2-binary is the fastest and simplest way to resolve the pg_config executable not found error.