Fix pg_config Executable Not Found When Installing psycopg2

You will learn what pg_config does during a psycopg2 source installation, why your interactive shell's PATH can differ from sudo's environment, and how to pass a correct executable path to the build.

psycopg2 is a Python adapter for PostgreSQL. When it is installed from source, it compiles native C code that must link against PostgreSQL client libraries.

pg_config is a PostgreSQL program that reports where those libraries and header files are installed. For example, it can provide locations for:

• C header files such as libpq-fe.h
• PostgreSQL client libraries such as libpq
• PostgreSQL build and version information

During installation, psycopg2 runs pg_config as an executable. It is not enough for a file to exist: the installation process must be able to locate and execute that exact file.

A frequent source of confusion is that this works in your normal shell:

which pg_config

but the package build is run through sudo. sudo may replace or restrict PATH for security. As a result, root's environment may not include /usr/pgsql-9.1/bin, even though your user's environment does.

Think of PATH as a list of drawers that the shell searches for a tool.

When you type pg_config, your shell checks each drawer listed in your PATH until it finds the tool. When you run sudo pip install ..., the installation may use a different person’s drawer list: root’s PATH.

The tool can be sitting safely in /usr/pgsql-9.1/bin, but if root is not told to search that drawer, the build reports that it cannot find it.

The PATH variable contains directories, separated by colons. It should contain the directory that holds a command, not the command itself.

export PATH="/usr/pgsql-9.1/bin:$PATH"

Verify both that the file exists and that it can run:

ls -l /usr/pgsql-9.1/bin/pg_config
/usr/pgsql-9.1/bin/pg_config --version

To make that directory available only for one installation command:

sudo env PATH="/usr/pgsql-9.1/bin:$PATH" pip install psycopg2

The env command sets PATH for the command launched by sudo. This avoids relying on sudo to preserve your normal shell environment.

If building from a source checkout or source archive, pass the full file path—not merely its directory—to the build option:

python setup.py build_ext --pg-config=/usr/pgsql-9.1/bin/pg_config build

A setup.cfg configuration uses the same idea:

Consider this command:

sudo env PATH="/usr/pgsql-9.1/bin:$PATH" pip install psycopg2

1. Your current shell expands $PATH to its current list of directories.
2. env creates a PATH beginning with /usr/pgsql-9.1/bin.
3. sudo runs pip with that explicitly supplied environment value.
4. pip downloads or reads the psycopg2 source distribution.
5. The build runs pg_config from /usr/pgsql-9.1/bin/pg_config.
6. pg_config tells the build where PostgreSQL headers and libraries are installed.
7. psycopg2 compiles its extension, assuming the needed compiler and PostgreSQL development files are installed.

Useful diagnostics compare the two environments:

command -v pg_config
sudo command -v pg_config
  PATH=  -v pg_config

Native Python packages commonly need external tools during installation.

• Database adapters: psycopg2 uses PostgreSQL development information from pg_config.
• Image packages: packages may need C compilers and image-library headers.
• Cryptography and networking packages: builds can require OpenSSL headers and libraries.
• CI pipelines: a build agent may have the correct tools installed, but fail because its non-interactive PATH is different.
• Containers: a Docker build can install runtime libraries but omit development packages, causing source builds to fail.

The general debugging pattern is: check the executable path, check which user runs the build, and check that the executable can run in that environment.

In real projects, developers usually avoid depending on an accidentally configured interactive shell.

Common practices include:

• Use explicit paths in build scripts when a nonstandard PostgreSQL installation is required.

  PG_CONFIG=/usr/pgsql-9.1/bin/pg_config
  export PATH="$(dirname "$PG_CONFIG"):$PATH"
  pip install psycopg2
  

• Install development dependencies in provisioning scripts before installing Python requirements. On RPM-based systems, this commonly includes PostgreSQL development packages and a compiler toolchain.

• Keep runtime and build dependencies separate. An application may need only PostgreSQL client libraries at runtime, while compiling psycopg2 also requires headers and pg_config.

• Make CI environments reproducible. Store required system-package installation and environment configuration in CI configuration or container build files instead of relying on a developer’s shell profile.

• Avoid unnecessary sudo pip. Installing Python packages into a virtual environment generally avoids system-wide permission issues and reduces differences between user and root environments.

Adding the executable instead of its directory to PATH

Incorrect:

export PATH="/usr/pgsql-9.1/bin/pg_config:$PATH"

Correct:

export PATH="/usr/pgsql-9.1/bin:$PATH"

PATH contains directories only.

Giving setup.cfg a directory rather than an executable

Incorrect:

[build_ext]
pg_config = /usr/pgsql-9.1/bin/

Correct:

[build_ext]
pg_config = /usr/pgsql-9.1/bin/pg_config

The option expects the full path to the pg_config program.

Checking only the normal user environment

This can succeed:

 pg_config

# Check whether the executable exists and runs
ls -l /usr/pgsql-9.1/bin/pg_config
/usr/pgsql-9.1/bin/pg_config --version

# Check the current user versus the sudo environment
command -v pg_config
sudo command -v pg_config

# Install with an explicit PATH for this command
sudo env PATH="/usr/pgsql-9.1/bin:$PATH" pip install psycopg2

# Build source using an explicit executable path
python setup.py build_ext --pg-config=/usr/pgsql-9.1/bin/pg_config build

Rules:

• PATH contains directories, separated by :.
• pg_config settings need the full executable path.
• The user running the build must be able to find and execute pg_config.
• If discovery succeeds but compilation fails, check PostgreSQL development headers and compiler dependencies.

Why does which pg_config work but pip install fail?

The installation may run under sudo, a service account, a CI runner, or another environment with a different PATH.

Should I add pg_config itself to PATH?

No. Add its containing directory, such as /usr/pgsql-9.1/bin.

What should the pg_config value in setup.cfg be?

Use the full executable filename:

pg_config = /usr/pgsql-9.1/bin/pg_config

How can I check whether sudo can find pg_config?

Run:

sudo command -v pg_config

If it prints nothing, use an explicit PATH for the install command or configure the root environment appropriately.

Why does psycopg2 need pg_config?

A source build needs PostgreSQL’s client header and library locations so it can compile and link its native extension.

• Environment variables — PATH is an environment variable passed to processes.
• Shell command lookup — explains how a shell resolves pg_config from a command name.
• sudo environment handling — explains why privileged commands may use a restricted PATH.
• Python virtual environments — provide isolated Python package installations without system-wide sudo pip.
• Native Python extensions — packages with C code require compilers, headers, and system libraries.
• PostgreSQL development packages — provide headers, libraries, and build metadata used by database clients.
• pip source distributions — source installs run build steps locally, unlike prebuilt binary package installs.