[Updated] How to Fix "Error: Pg_config Executable Not Found." in Python

Sometimes, you might encounter the “Error: pg_config executable not found.” error while installing or using pyscopg2 with Python and PostgreSQL. The error looks something like:

Error: pg_config executable not found. 
Please add the directory containing pg_config to the PATH

This typically happens when the psycopg2 library has trouble communicating with your PostgreSQL database. This article will guide you through some important concepts around the error, what causes it, and how to fix it on different operating systems.

Psycopg2 is a database adapter for PostgreSQL databases compliant with Python DB API 2.0 specifications. It facilitates secure and efficient interaction with PostgreSQL for Python and is ideal for multi-threaded Python applications. The Psycopg2 library acts as a bridge between the two, enabling Python to seamlessly communicate with PostgreSQL DB.

pg_config is a configuration utility file used during the installation of psycopg2. It retrieves information (the locations of headers and other libraries for PostgreSQL) about the installed PostgreSQL version, which psycopg2 needs to interact with the PostgreSQL client library (like libpq). This ensures compatibility between the psycopg2 library and your specific PostgreSQL installation.

The error shows up in your terminal for several reasons. Here are the common ones:

• PostgreSQL is not installed
• Missing psycopg2 library
• The PATH environment variable isn’t updated
• Your system couldn’t locate the pg_config utility file

Here are the various fixes for the error:

Fix 1: Install PostgreSQL

Here’s how to install PostgreSQL development packages for different operating systems:

For Windows:

1. Visit the official site to download PostgreSQL for Windows.
2. Select the desired pgsql version and system architecture (x86-64 or x86-32)
3. Run the installer.

Also Read: How to Fix “Objects are not Valid as a React Child” Error in React

For macOS:

If you’re using Homebrew as your graphical package manager for macOS, open the terminal and run the command:

brew install postgresql

If you’re using MacPorts to manage your packages, you might need to specify the exact version you want to install after the “postgresql” command. Run the following in your terminal like below to install PostgreSQL v14 with MacPorts:

sudo port install postgresql14-server

For Linux (based on Ubuntu/Debian):

Use the following command to install the libpq-dev development package for PostgreSQL and the Python development libraries on Linux.

# Replace python3-dev with pythonX-dev for your Python version (e.g., python2-dev)
sudo apt-get install libpq-dev python3-dev  

Fix 2: Install psycopg2

Once you’re sure about the correct installation of the PostgreSQL dev package based on your OS, install the psycopg2 library with pip using the following command:

pip install psycopg2

Fix 3: Update System PATH Environment Variable

Sometimes, you may have to update the system PATH env variable manually by adding a directory for pg_config which enables Python to locate the pg_config file correctly — that’s necessary for installing the psycopg2 library. Here’s how you can add a directory for different operating systems:

For Windows:

Run the following command from the Command Prompt to permanently add the specified directory to the PATH environment variable:

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

This command will update the PATH env variable for future Command Prompt sessions. However, it’s important to note that the changes might not take effect in the current session; a new Command Prompt window may need to be opened to reflect the update.

For Linux/macOS:

Add the path to the pg_config directory to the PATH env variable by modifying the ~/.bashrc or ~/.bash_profile file with the following line:

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

This command appends the directory containing pg_config to the existing PATH variable, ensuring that the system can locate the executable.

Remember to replace /path/to/pg_config/directory or C:\path\to\pg_config\directory with the actual path where pg_config is located on your system. Here are the common path locations for pg_config based on your operating system:

For Windows:

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

For macOS:

/usr/local/pgsql/bin/pg_config

For Linux:

/usr/pgsql-<pgsql_version>/bin/pg_config

Here’s a quick summary of ways to fix the “pg_config executable not found.” error in Python:

By following the aforementioned steps, you should be able to resolve the "pg_config executable not found." error and successfully install psycopg2 for interacting with your PostgreSQL database from Python.