pip install psycopg2 fails with 'Failed building wheel for psycopg2'
ERROR: Failed building wheel for psycopg2Short 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.
Fix it fast
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 --version2Match what you see, then jump to its fix
- 1
libpq-fe.h: No such file or directory, or pg_config not foundThe libpq development files or pg_config are missingFix - 2
error: Python.h: No such file or directoryThe Python header files are missingFix - 3
The 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
- 1
What does the error look like?
ERROR: Failed building wheel for psycopg2error: Python.h: No such file or directoryerror: libpq-fe.h: No such file or directorypg_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/:$PATH3Verify
pg_config now answers and pip can build.
pg_config --version
pip install psycopg2Confirmed by psycopg.org
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.h2Fix
Install the Python development package that matches your interpreter, then retry inside the virtual environment.
sudo apt install python3-dev3Verify
Build again.
pip install --no-cache-dir psycopg2Confirmed by psycopg.org
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 --version2Fix
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
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Databases
Installing the Airflow MySQL provider fails on pkg-config or mysqlclient
Building the mysqlclient wheel fails during the install
The Airflow MySQL provider depends on mysqlclient, which pip compiles against the MySQL C client library.
2 causes, each with a fixDatabases
pip install mysqlclient fails to build on Windows, Linux or macOS
error: metadata-generation-failed
mysqlclient is a C extension.
3 causes, each with a fixDatabases
pyodbc cannot find the SQL Server ODBC driver on Linux
Can't open lib 'ODBC Driver 17 for SQL Server' : file not found
The driver manager looked for a driver library that is not installed or not registered under that name.
3 causes, each with a fixDatabases
pip cannot build the mariadb package because mariadb_config is missing
Please make sure, that MariaDB Connector/C is installed on your system.
The mariadb Python package builds against MariaDB Connector/C, and it finds the library through the mariadb_config program.
3 causes, each with a fixDatabases
Python cannot import psycopg2 even though you installed it
No module named 'psycopg2.extensions'
Python found no psycopg2 package in the interpreter that runs your code.
3 causes, each with a fixDatabases
asyncpg InterfaceError: another operation is in progress with SQLAlchemy
InterfaceError raised from a FastAPI endpoint that runs several queries at once
A single database connection can run one operation at a time.
4 causes, each with a fix