Why You See ‘pg_config Executable Not Found’ and How to Fix It

Published On - August 25, 2025

ivan Blogging

When working with Python packages or PostgreSQL-related tools, you might encounter the following frustrating message: ‘pg_config executable not found’. If you’ve seen this error, you’re likely trying to install a package like psycopg2 or do development work that requires PostgreSQL to be properly configured on your machine. Understanding why this error occurs — and how to solve it — can save you hours of confusion. Let’s dive into what’s happening and how to fix it effectively.

What Is pg_config and Why It’s Important

pg_config is a utility that comes with PostgreSQL and provides information about the installed library and binaries. It’s used primarily during the compilation of C extensions or libraries that interface with PostgreSQL.

Packages like psycopg2 require this tool to compile correctly. When you try to install such a package using pip, the installer attempts to locate pg_config to verify where PostgreSQL is installed and to link necessary files.

If pg_config is not found, it usually means your system does not have the necessary PostgreSQL development libraries installed — or they’re not in the system’s PATH.

Common Scenarios Where This Error Appears

  • You’re trying to install psycopg2 or another PostgreSQL adapter with pip.
  • You’re developing software that links to PostgreSQL’s C libraries.
  • You recently upgraded or changed your PostgreSQL installation.
  • You’re setting up a new project on a clean machine with no database tools configured.

How to Fix the ‘pg_config Executable Not Found’ Error

The good news is that fixing this error is relatively straightforward, depending on your operating system. Below are solutions for all major platforms.

On Debian or Ubuntu

Use the official package manager to install the PostgreSQL development files:

sudo apt update
sudo apt install libpq-dev

This will install pg_config and place it in a location that pip can automatically find.

On Red Hat, CentOS, or Fedora

Install the PostgreSQL development package:

sudo dnf install postgresql-devel

Alternatively, for older systems using yum:

sudo yum install postgresql-devel

On macOS

If you have Homebrew installed (which is highly recommended for developers), simply install PostgreSQL using:

brew install postgresql

After installation, make sure pg_config is in your PATH. You can check this with:

which pg_config

If it’s not found, try adding this to your shell profile (like .zshrc or .bash_profile):

export PATH="/opt/homebrew/opt/postgresql/bin:$PATH"

On Windows

Fixing this error on Windows is slightly more involved:

  1. First, install PostgreSQL from the official installer at postgresql.org.
  2. During installation, note the path where PostgreSQL is installed (for example, C:\Program Files\PostgreSQL\15\bin).
  3. Then, add that bin directory to your system’s environment variables like this:
    1. Search for “Environment Variables” in the Start Menu.
    2. Under “System Variables”, find the PATH variable and click “Edit”.
    3. Add your PostgreSQL bin path and click OK.

Now restart your terminal or IDE and try running pg_config again to confirm it’s recognized.

Alternative Workaround: Install Binary Python Wheels

If you don’t want to mess with compilers and system packages, consider using a binary version of the library when available. For instance, instead of running:

pip install psycopg2

Use:

pip install psycopg2-binary

This version includes precompiled binaries and doesn’t require pg_config to be present. However, note that this is not ideal for production, as the binary package might lack certain optimizations or be harder to debug.

Final Thoughts

The error message ‘pg_config executable not found’ might feel like an insurmountable hurdle at first, but it’s actually a straightforward problem with well-documented solutions. Whether you’re working on Linux, macOS, or Windows, the common theme is that you need to install PostgreSQL development tools and ensure your system’s PATH knows where to find pg_config. Once it’s correctly installed, your Python packages and database tools will be up and running smoothly.

So the next time you bump into this error, remember: it’s not a bug in your code — it’s just a missing executable that your development tools rely on.