pg_config executable not found
Categories:
Resolving 'pg_config executable not found' Error with Psycopg2
Encountering 'pg_config executable not found' when installing psycopg2? This article guides you through diagnosing and fixing this common Python-PostgreSQL connection issue.
The error message "pg_config executable not found" is a frequent hurdle for developers attempting to install the psycopg2 Python adapter for PostgreSQL. This issue typically arises because psycopg2 needs to compile C extensions during installation, and pg_config is a utility provided by PostgreSQL that supplies necessary compilation flags and library paths. Without pg_config, the installation process fails to locate the required PostgreSQL development headers and libraries.
Understanding the Root Cause
When you run pip install psycopg2 (or psycopg2-binary), pip attempts to build the psycopg2 package. For the non-binary version, this involves compiling C code that interfaces directly with PostgreSQL's client libraries. The pg_config utility is crucial in this step. It's a command-line tool that reports configuration parameters for an installed PostgreSQL version, such as include directories, library directories, and compiler options. If your system cannot find pg_config in its PATH, or if PostgreSQL development headers are not installed, the psycopg2 build process will fail.
flowchart TD
A[pip install psycopg2] --> B{Locate pg_config?}
B -- No --> C[Error: pg_config not found]
B -- Yes --> D{PostgreSQL Dev Headers Installed?}
D -- No --> E[Error: Missing Headers]
D -- Yes --> F[Compile Psycopg2 C Extensions]
F --> G[Psycopg2 Installed Successfully]Flowchart illustrating the psycopg2 installation process and potential failure points.
Common Solutions and Installation Strategies
There are several approaches to resolve the pg_config error, ranging from installing development packages to using pre-compiled binary versions of psycopg2. The best solution often depends on your operating system and whether you need specific PostgreSQL client library versions.
psycopg2-binary first. It often bypasses compilation issues entirely, making it the quickest fix for many users.1. Option 1: Install psycopg2-binary
The simplest solution is often to install the psycopg2-binary package. This version includes pre-compiled C extensions, eliminating the need for pg_config during installation. This is highly recommended for most users unless you have specific reasons to compile psycopg2 yourself.
2. Option 2: Install PostgreSQL Development Headers
If psycopg2-binary isn't suitable or doesn't work, you'll need to ensure your system has the PostgreSQL development headers and libraries installed. These packages typically include pg_config and the necessary files for compilation.
3. Option 3: Ensure pg_config is in your PATH
After installing the development packages, verify that the pg_config executable is accessible via your system's PATH environment variable. If it's installed but not found, you might need to manually add its directory to PATH or specify its location during pip installation.
4. Option 4: Specify pg_config location during pip install
As a last resort, if pg_config is installed but pip still can't find it, you can explicitly tell pip where to find it using environment variables.
Detailed Solutions by Operating System
The exact commands to install PostgreSQL development packages vary by operating system.
Linux (Debian/Ubuntu)
For Debian-based systems like Ubuntu, you need to install the libpq-dev package. This package provides the development files for PostgreSQL client applications, including pg_config.
sudo apt update
sudo apt install libpq-dev
pip install psycopg2
Installing PostgreSQL development headers on Debian/Ubuntu and then psycopg2.
Linux (CentOS/RHEL/Fedora)
On Red Hat-based systems, the equivalent package is postgresql-devel.
sudo yum install postgresql-devel # For CentOS/RHEL 7 and older
sudo dnf install postgresql-devel # For Fedora and CentOS/RHEL 8+
pip install psycopg2
Installing PostgreSQL development headers on CentOS/RHEL/Fedora and then psycopg2.
macOS
On macOS, the easiest way to get PostgreSQL and its development headers is via Homebrew.
brew install postgresql
export PATH="/usr/local/opt/postgresql/bin:$PATH" # Add to .bash_profile or .zshrc
pip install psycopg2
Installing PostgreSQL via Homebrew and setting PATH on macOS.
pg_config path is correctly added to your shell's configuration file (e.g., ~/.bash_profile, ~/.zshrc) and then reload your shell or open a new terminal.Windows
On Windows, compiling psycopg2 from source is significantly more complex due to the lack of a standard C compiler and build environment. The recommended approach is almost always to use psycopg2-binary.
pip install psycopg2-binary
Recommended installation for psycopg2 on Windows.
psycopg2 from source on Windows without a proper build environment (like MSVC or MinGW) and correctly configured PostgreSQL development files is generally not advised for beginners.Verifying pg_config Location
After installing the necessary packages, you can verify if pg_config is found and its location using the which or where command.
Linux/macOS
which pg_config
Windows (Command Prompt)
where pg_config
Windows (PowerShell)
Get-Command pg_config
If the command returns a path (e.g., /usr/bin/pg_config or /usr/local/opt/postgresql/bin/pg_config), then pg_config is found. If it returns nothing or an error, it's either not installed or not in your system's PATH.
Manually Specifying pg_config Path
If pg_config is installed but pip still fails, you can set the PG_CONFIG environment variable before running pip install.
Linux/macOS
export PG_CONFIG=/path/to/your/pg_config pip install psycopg2
Windows (Command Prompt)
set PG_CONFIG=C:\path\to\your\pg_config.exe pip install psycopg2
Windows (PowerShell)
$env:PG_CONFIG="C:\path\to\your\pg_config.exe" pip install psycopg2
Replace /path/to/your/pg_config with the actual path found in the verification step.