How to Fix 'pg_config executable not found' Error When Installing psycopg2

If you’ve tried to install the psycopg2 Python package to connect to PostgreSQL databases, you may have encountered the frustrating pg_config executable not found error. This guide explains what causes this error and provides clear steps to resolve it on various operating systems.

What is the ‘pg_config executable not found’ Error?

The pg_config tool provides information about the installed version of PostgreSQL. Many packages like psycopg2 rely on pg_config during installation to locate the necessary PostgreSQL files and libraries. If pg_config cannot be found, the installation fails with an error like:

Error: pg_config executable not found.

Common Causes of the ‘pg_config executable not found’ Error

There are a few main reasons you may see this error:

1. PostgreSQL is not installed
2. The pg_config executable is not in the system’s PATH
3. Required PostgreSQL development libraries and headers are missing

Let’s look at how to address each of these issues.

How to Fix the ‘pg_config executable not found’ Error

1. Install PostgreSQL

First, make sure PostgreSQL is installed on your system. You can download the appropriate installer for your operating system from the official PostgreSQL website.

2. Locate pg_config and Add it to PATH

The pg_config executable is included with PostgreSQL, but may not be in the system’s PATH. Find the location of pg_config and add its directory to PATH:

Linux

Common locations:

• /usr/pgsql-<version>/bin/pg_config
• /usr/local/pgsql/bin/pg_config

Add to PATH:

export PATH=$PATH:/path/to/pg_config/directory

macOS

Common location (Postgres.app):

• /Applications/Postgres.app/Contents/Versions/latest/bin/pg_config

Add to PATH:

export PATH=$PATH:/Applications/Postgres.app/Contents/Versions/latest/bin

Windows

Common location:

• C:\Program Files\PostgreSQL\<version>\bin\pg_config.exe

Add to PATH:

setx PATH "%PATH%;C:\path\to\pg_config\directory"

3. Install PostgreSQL Development Libraries

To compile psycopg2, you need the PostgreSQL development libraries and headers. Install them using your system’s package manager:

Linux

• Ubuntu/Debian: sudo apt install libpq-dev
• CentOS/RHEL: sudo yum install postgresql-devel

macOS

Install with Homebrew:

brew install postgresql

Windows

The libraries are included with the PostgreSQL installer from the official website.

Install psycopg2

With PostgreSQL installed and pg_config in PATH, you can now install psycopg2:

pip install psycopg2

If you prefer to avoid building from source, you can install the pre-built psycopg2-binary package instead:

pip install psycopg2-binary

However, note that psycopg2-binary is recommended only for development and testing, not production.

FAQs

Conclusion

By following the steps outlined here, you should be able to resolve the pg_config executable not found error and successfully install psycopg2 to start using PostgreSQL in your Python projects.