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

# Partial Output:
# Error: pg_config executable not found.
# ...
# If you prefer to avoid building psycopg2 from source, please install the PyPI
# 'psycopg2-binary' package instead.
# ----------------------------------------
# ERROR: Command errored out with exit status 1: ...

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.

note

What is psycopg2-binary? The psycopg2-binary package is a standalone version of psycopg2 that includes its own pre-compiled C library dependencies. It is ideal for development and for environments where you don't want to manage system-level PostgreSQL libraries. However, for serious production environments, the official psycopg2 documentation recommends building from source to ensure you are linked against the exact version of libpq provided by your production operating system.

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:

# Install the PostgreSQL client development library and Python headers
sudo apt-get update
sudo apt-get install libpq-dev python3-dev

# Now, the original command will succeed
pip install psycopg2

On Fedora / RHEL / CentOS

Solution:

# Install the PostgreSQL development library
sudo dnf install postgresql-devel

# Now, the original command will succeed
pip install psycopg2

On macOS (using Homebrew)

Solution:

# Install the full PostgreSQL package with Homebrew
brew install postgresql

# Homebrew may advise you to add postgresql to your PATH.
# Now, the original command will succeed
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

Your Goal	Recommended Solution
Quick fix for development or environments without system-level dependencies.	Install the pre-compiled binary: pip install psycopg2-binary
Production use or need to compile against a specific system libpq version.	Install the PostgreSQL development headers for your OS (e.g., sudo apt-get install libpq-dev) and then run pip install psycopg2.

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.