Fixing Error: pg_config executable not found

What Does the ‘pg_config executable not found’ Error Mean?

When trying to install psycopg2 to connect to PostgreSQL from Python, you may see this error during the pip install process:

pg_config executable not found.

Error: pg_config executable not found. Please add it to your path.

OSError: pg_config executable not found.

postgres_config_path error: pg_config executable not found

This occurs because psycopg2 depends on a utility called pg_config that contains information about your PostgreSQL installation like directory paths and versioning. The pg_config executable is normally included with PostgreSQL.

If pip cannot locate the pg_config program during psycopg2’s installation, you’ll see this error. Let’s go over how to resolve it!

Ensure PostgreSQL is Installed

The first step is verifying that a PostgreSQL server is actually installed on your system before attempting to install psycopg2. The error often means no PostgreSQL installation exists for pg_config to be found.

On Linux, make sure packages like postgresql or postgresql-server are present from your distribution’s package manager.

On macOS, check that Postgres.app or a Homebrew postgres package has been installed.

With PostgreSQL missing entirely, the pg_config executable unsurprisingly won’t be available. Install PostgreSQL for your operating system before retrying psycopg2.

Install pg_config Manually

If PostgreSQL itself is installed but pg_config still isn’t found, try installing just the pg_config executable separately.

On Debian/Ubuntu:

sudo apt install libpq-dev

On Fedora/CentOS:

sudo yum install postgresql-devel

On macOS w/ Homebrew:

brew install libpq

This adds pg_config to your system independently of the full PostgreSQL server install.

Now retry installing psycopg2 after adding pg_config.

Specify the pg_config Path Manually

If pg_config was found in a non-standard location not in your PATH, explicitly specify its path during psycopg2 installation using the –pg-config flag:

pip install psycopg2 --pg-config /custom/path/to/pg_config

This bypasses the need for pip to locate pg_config itself.

You can find the path by running an updatedb and locate pg_config if not standard.

Specifying the full path also resolves issues of pg_config being in unsearchable network directories.

Use a Containerized PostgreSQL

When using a Docker, Podman, or containerized PostgreSQL database in development rather than a system-level installation, the container won’t include pg_config by default.

Specify an administrative container that has the development libraries:

docker run -it --rm postgres pg_config

Or use Docker’s volumes to map your pg_config from the host inside the container:

docker run -v /path/to/pg_config:/pg_config postgres

This provides containerized database setups access to the crucial pg_config tool.

Install Build Dependencies

Some Linux distributions require you to install additional packages like Python development headers before psycopg2 can build properly:

Debian/Ubuntu:

sudo apt install python-dev

Fedora/CentOS:

sudo yum install python-devel

Arch Linux:

sudo pacman -S python-devel

This installs development libraries enabling psycopg2 to compile successfully.

Upgrade Package Managers

Old or outdated system package managers may not resolve psycopg2 dependencies properly.

Upgrade pip, setuptools, and wheel on Linux:

pip install pip setuptools wheel --upgrade

And upgrade Homebrew on macOS:

brew update

Before reattempting installation after updating. Newer versions help properly fetch requirements like pg_config.

Recap of Resolutions

To quickly recap, here are the key solutions to the “pg_config executable not found” error when installing psycopg2:

• Ensure PostgreSQL is installed before psycopg2
• Install just pg_config separately as needed
• Provide full pg_config path with –pg-config
• Use containerized PostgreSQL with pg_config access
• Install Python/OS development libraries
• Upgrade pip/package managers if outdated

Running through these troubleshooting steps when encountering the pg_config error will help isolate the underlying issue and allow psycopg2 installation to succeed.

Key Takeaways for Fixing pg_config Issues

To summarize, the main takeaways for resolving “pg_config executable not found” errors:

• The pg_config utility contains key PostgreSQL install details
• psycopg2 relies on pg_config during installation
• If pg_config is missing, supply path with –pg-config
• For container PostgreSQL, provide pg_config access
• Install needed dependencies on your specific system
• Upgrade pip and package managers if old

Ensuring psycopg2 can find a proper pg_config executable by following this guidance will ultimately resolve the error and have you connecting Python to PostgreSQL in no time.

Smooth PostgreSQL Database Access from Python

With PostgreSQL being a popular database choice for many Python developers, resolving “pg_config executable not found” errors is a critical troubleshooting skill.

Now you’re equipped with in-depth knowledge for debugging exactly why psycopg2 cannot find pg_config needed during installation on Linux, macOS, and across local and containerized PostgreSQL environments.

Whether the issue stems from a missing library, outdated package manager, non-standard path, or any other cause – this guide provides actionable solutions to overcome the error and successfully install psycopg2. Never let a missing pg_config thwart your Python database programming again!