Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pip install psycopg2 fails with 'Failed building wheel for psycopg2'

ErrorERROR: Failed building wheel for psycopg2

Short answer

psycopg2 is compiled from source when pip finds no ready wheel for your platform. The build needs a C compiler, the Python headers, the libpq headers and pg_config. Install the missing piece the error names, or use psycopg2-binary, or move the project to psycopg 3 with its binary extra.

  • Applies to psycopg2 2.9, Python 3.12, Django 5.2, Ubuntu 24.04, macOS
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether pg_config is on your PATH. It is shipped with the libpq development files, and the psycopg2 build uses it to find the headers.

    pg_config --version
  2. 2Match what you see, then jump to its fix

    1. 1libpq-fe.h: No such file or directory, or pg_config not foundThe libpq development files or pg_config are missingFix
    2. 2error: Python.h: No such file or directoryThe Python header files are missingFix
    3. 3The build keeps failing on a machine where you cannot install system packagesYou only need it to work, and do not want a compiler on the boxFix

What does the error look like?

  • ERROR: Failed building wheel for psycopg2
  • error: Python.h: No such file or directory
  • error: libpq-fe.h: No such file or directory
  • pg_config --version fails or is not found

Cause 1 of 3

The libpq development files or pg_config are missing

1Check

pg_config comes with the libpq headers (libpq-dev on Debian and Ubuntu). It is only needed to compile; it is not needed to run the app.

which pg_config || echo 'pg_config not on PATH'

2Fix

Install the libpq development package, and a compiler if none is present. If PostgreSQL is installed but pg_config is not found, add the bin directory that holds pg_config to PATH before running pip.

sudo apt install libpq-dev gcc
# if pg_config exists but is not on PATH:
export PATH=/usr/lib/postgresql/16/bin/:$PATH

3Verify

pg_config now answers and pip can build.

pg_config --version
pip install psycopg2

Confirmed by psycopg.org

Did this fix it?

Cause 2 of 3

The Python header files are missing

1Check

System Python on Linux often ships without its headers. They live in the python3-dev package.

python3 -c "import sysconfig; print(sysconfig.get_paths()['include'])" && ls $(python3 -c "import sysconfig; print(sysconfig.get_paths()['include'])")/Python.h

2Fix

Install the Python development package that matches your interpreter, then retry inside the virtual environment.

sudo apt install python3-dev

3Verify

Build again.

pip install --no-cache-dir psycopg2

Confirmed by psycopg.org

Did this fix it?

Cause 3 of 3

You only need it to work, and do not want a compiler on the box

1Check

psycopg2-binary is a precompiled wheel with its own libpq, so it needs no compiler and no pg_config. The psycopg2 authors call it suited to beginners and advise building from source for production.

pip --version && python3 --version

2Fix

Install psycopg2-binary for development. For new code, Django supports psycopg 3.1.8 or newer and recommends it, so you can install the binary extra of psycopg instead.

pip install psycopg2-binary
# or, with psycopg 3:
pip install "psycopg[binary]"

3Verify

Import the driver inside the same environment Django uses.

python -c "import psycopg2; print(psycopg2.__version__)"

Confirmed by docs.djangoproject.com

Did this fix it?

How do I stop it coming back?

  • Pin the driver in requirements.txt and build it in the same image you deploy.
  • In Docker, install libpq-dev and gcc in the build stage only.
  • Prefer psycopg 3 for new projects, since Django notes that psycopg2 support may be removed later.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.