During installation or while building psycopg2 from source, you might encounter an error that states ‘pg_config is required to build psycopg2 from source’. This article will explain what this error means, the common reasons it occurs, and how to resolve it with proper code examples.

What Does ‘pg_config is Required to Build psycopg2 from Source’ Mean?

The error ‘pg_config is required to build psycopg2 from source’ typically indicates that the pg_config utility, which is part of the PostgreSQL development package, is not available in your system’s PATH. pg_config provides information about the installed version of PostgreSQL, such as compiler flags, library paths, and version information. This utility is essential for building psycopg2 from source as it helps locate the necessary PostgreSQL files.

Common Reasons for the Error

1. PostgreSQL Development Package Not Installed

The most common reason for encountering this error is that the PostgreSQL development package is not installed on your system. Without this package, pg_config is not available.

Example: On a Debian-based system, if you try to install psycopg2 without having the PostgreSQL development package, you might encounter this error:

pip install psycopg2

Output

Error: pg_config executable not found.

2. Incorrect PATH Configuration

Another reason for this error is that pg_config is installed but not in your system’s PATH. This means that the system cannot locate pg_config even though it is installed.

Example: You might have installed the PostgreSQL development package, but if pg_config is not in the PATH, you’ll still face the same error:

pip install psycopg2

Output

Error: pg_config executable not found.

3. Virtual Environment Issues

Sometimes, the issue arises from using a virtual environment where the PATH configuration does not include the directory containing pg_config.

Example: If you are working inside a virtual environment and try to install psycopg2, you might see the error if the virtual environment does not have access to pg_config.

# Inside a virtual environment
pip install psycopg2

Output

Error: pg_config executable not found.

Approaches to Solve ‘pg_config is Required to Build psycopg2 from Source’

1. Installing PostgreSQL Development Package

The first step is to ensure that the PostgreSQL development package is installed on your system.

For Debian-based systems (e.g., Ubuntu):

sudo apt-get install libpq-dev

For Red Hat-based systems (e.g., CentOS, Fedora)

sudo yum install postgresql-devel

For Windows using Homebrew:

pip install postgresql

2. Adding pg_config to PATH

If pg_config is installed but not in your PATH, you can add it manually. First, locate pg_config:

find / -name pg_config 2>/dev/null

Then, add the directory containing pg_config to your PATH. For example, if pg_config is located in /usr/pgsql-13/bin, you can add it to your PATH as follows:

export PATH=$PATH:/usr/pgsql-13/bin

To make this change permanent, add the above line to your shell configuration file (e.g., .bashrc, .zshrc).

3. Ensuring Virtual Environment Access

If you’re working within a virtual environment, make sure the environment has access to pg_config. One way to ensure this is to activate the virtual environment after installing the PostgreSQL development package.

Example:

source /path/to/your/virtualenv/bin/activate

pip install psycopg2

Alternatively, you can create a virtual environment after installing the PostgreSQL development package:

sudo apt-get install libpq-dev
python -m venv myenv
source myenv/bin/activate
pip install psycopg2

By following these approaches, you should be able to resolve the ‘pg_config is required to build psycopg2 from source’ error and successfully install psycopg2.

Conclusion

The ‘pg_config is required to build psycopg2 from source’ error is a common issue encountered when installing the psycopg2 library. This error typically arises due to the absence of the PostgreSQL development package, incorrect PATH configuration, or issues within a virtual environment. By ensuring the PostgreSQL development package is installed, adding pg_config to your PATH, and managing virtual environment configurations, you can effectively resolve this error and continue with your development work.