psycopg/psycopg2 · critical · Warning

Unable to find 'pg_config' file in '{self.pg_config_exe}'

Error message

Unable to find 'pg_config' file in '{self.pg_config_exe}'

What it means

Raised in PostgresConfig.query() (setup.py:113) as a Warning when subprocess.run([pg_config_exe, '--attr']) raises OSError - the resolved pg_config path does not exist, is not executable, or cannot be spawned. psycopg2's source build needs pg_config to discover include/library directories; finalize_options() catches this Warning, prints 'Error: ...', and calls sys.exit(1), aborting the install. The path was obtained from --pg-config, setup.cfg, PATH autodetect, or (Windows) the registry.

Source

Thrown at setup.py:113

If you prefer to avoid building psycopg2 from source, please install the PyPI
'psycopg2-binary' package instead.

For further information please check the 'doc/src/install.rst' file (also at
<https://www.psycopg.org/docs/install.html>).

""")
            sys.exit(1)

    def query(self, attr_name, *, empty_ok=False):
        """Spawn the pg_config executable, querying for the given config
        name, and return the printed value, sanitized. """
        try:
            pg_config_process = subprocess.run(
                [self.pg_config_exe, "--" + attr_name],
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE)
        except OSError:
            raise Warning(
                f"Unable to find 'pg_config' file in '{self.pg_config_exe}'")
        if pg_config_process.returncode:
            err = pg_config_process.stderr.decode(errors='backslashreplace')
            raise Warning(f"pg_config --{attr_name} failed: {err}")
        result = pg_config_process.stdout.decode().strip()
        if not result and not empty_ok:
            raise Warning(f"pg_config --{attr_name} is empty")
        return result

    def find_on_path(self, exename, path_directories=None):
        if not path_directories:
            path_directories = os.environ['PATH'].split(os.pathsep)
        for dir_name in path_directories:
            fullpath = os.path.join(dir_name, exename)
            if os.path.isfile(fullpath):
                return fullpath
        return None

View on GitHub (pinned to 3a6d9d6ddc)

Solutions

1. Install the PostgreSQL dev package: Debian/Ubuntu 'apt-get install libpq-dev', Alpine 'apk add postgresql-dev', RHEL/Fedora 'dnf install libpq-devel', macOS 'brew install libpq' (and link) or install Postgres.app.
2. Skip the source build entirely: pip install psycopg2-binary (recommended for app deployment).
3. Point pip at the right binary: pip install psycopg2 --global-option build_ext --global-option --pg-config=/path/to/pg_config, or set pg_config in setup.cfg.

import os, shutil

def pg_config_is_runnable(path: str | None = None) -> bool:
    p = path or shutil.which('pg_config')
    return bool(p) and os.path.isfile(p) and os.access(p, os.X_OK)

# fail fast before pip install:
assert pg_config_is_runnable(), 'pg_config missing - install libpq-dev / postgresql-dev or use psycopg2-binary'

# Pre-flight in your Dockerfile / CI before installing psycopg2:
#   command -v pg_config >/dev/null || { apt-get update && apt-get install -y libpq-dev; }
#   pg_config --version

When it happens

Trigger: pip install psycopg2 (source build) on a host where the resolved pg_config path is wrong/missing. Triggers: bare/slim base images without PostgreSQL dev headers, a stale --pg-config value, a broken PATH, or a 32/64-bit mismatch where the registry pointed pg_config.exe at the wrong bitness.

Common situations: Alpine/slim Debian/Ubuntu containers without libpq-dev; macOS without Postgres.app or libpq in PATH; CI images lacking postgresql-server-dev-*; Windows installs where the registry Base Directory is gone.

Related errors

• pg_config --{attr_name} failed: {err}
• pg_config --{attr_name} is empty
• no format specification supported by SQL
• no format conversion supported by SQL
• cannot switch from automatic field numbering to manual

AI-assisted analysis of psycopg/psycopg2@3a6d9d6ddc (2026-08-04). Data as JSON: /data/errors/e9877fb11ac819f1.json. Report an issue: GitHub.