pip install psycopg2 fails while building the Docker image
Python.h: No such file or directoryShort answer
The plain psycopg2 package compiles a C extension, so the image needs a compiler, the Python headers, the libpq headers and pg_config. Slim images have none of them. Either install those system packages before pip, or use psycopg2-binary, which ships precompiled.
Fix it fast
1Find out which cause you have
Find which header the compiler could not open, in the pip output of the failing build step.
docker build --progress=plain --no-cache . 2>&1 | grep -E 'Python.h|libpq-fe.h|pg_config'2Match what you see, then jump to its fix
What does the error look like?
Python.h: No such file or directorylibpq-fe.h: No such file or directory
Cause 1 of 3
The Python development headers are missing
1Check
The psycopg documentation lists a C compiler and the Python header files (python3-dev on Debian and Ubuntu) as requirements for a source build, and names this exact error as the sign they are missing.
docker run --rm python:3.12-slim sh -c 'ls /usr/local/include/python3.12/Python.h; which gcc'2Fix
Install a compiler and the headers before pip install, in the same Dockerfile layer, and clear the apt lists afterwards.
RUN apt-get update \
&& apt-get install -y --no-install-recommends build-essential python3-dev libpq-dev \
&& rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir psycopg23Verify
The build step completes.
docker build -t myapp .Confirmed by psycopg.org
Cause 2 of 3
libpq headers or pg_config are missing
1Check
The same page says the libpq headers (libpq-dev on Debian and Ubuntu) and the pg_config program are needed to compile. pg_config is only needed at build time.
docker run --rm python:3.12-slim sh -c 'pg_config --version'2Fix
Install libpq-dev for the headers before the pip step, then confirm pg_config runs. If pg_config is installed outside PATH, add its folder to PATH.
RUN apt-get update && apt-get install -y libpq-dev && rm -rf /var/lib/apt/lists/*3Verify
pg_config reports a version in the build stage.
docker build -t myapp . && docker run --rm myapp pg_config --versionConfirmed by psycopg.org
Cause 3 of 3
You only need a quick install: use the binary package
1Check
psycopg2-binary is a pre-compiled build that skips the build prerequisites. The docs say it is meant for getting started and that for production the source package is advised, because the wheel bundles its own libpq and libssl.
grep -n psycopg requirements.txt2Fix
Use psycopg2-binary for development images, and the source package with the system packages above for production.
RUN pip install --no-cache-dir psycopg2-binary3Verify
The import works inside the container.
docker run --rm myapp python -c "import psycopg2; print(psycopg2.__version__)"Confirmed by psycopg.org
How do I stop it coming back?
- Use a multi-stage build: compile in a builder stage, copy only the installed packages to the final image.
- Pin psycopg2 in requirements.txt.
- Keep the apt install and the cleanup in the same RUN line so the image stays small.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fix