Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pip install psycopg2 fails while building the Docker image

ErrorPython.h: No such file or directory

Short 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.

  • Applies to Docker Engine 27, Debian/Ubuntu based python:3.12 images, psycopg2 2.9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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'
  2. 2Match what you see, then jump to its fix

    1. 1Python.h: No such file or directoryThe Python development headers are missingFix
    2. 2libpq-fe.h: No such file or directorylibpq headers or pg_config are missingFix
    3. 3You do not want a compiler in the imageYou only need a quick install: use the binary packageFix

What does the error look like?

  • Python.h: No such file or directory
  • libpq-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 psycopg2

3Verify

The build step completes.

docker build -t myapp .

Confirmed by psycopg.org

Did this fix it?

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 --version

Confirmed by psycopg.org

Did this fix it?

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.txt

2Fix

Use psycopg2-binary for development images, and the source package with the system packages above for production.

RUN pip install --no-cache-dir psycopg2-binary

3Verify

The import works inside the container.

docker run --rm myapp python -c "import psycopg2; print(psycopg2.__version__)"

Confirmed by psycopg.org

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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