Python "fatal error: Python.h: No such file or directory"

A C extension is being compiled and the build needs the CPython development headers, which are not installed. Python.h lives in the -dev/-devel package, not the base interpreter.

What this error means

During a wheel build or setup.py build_ext, the C compiler stops with fatal error: Python.h: No such file or directory. The interpreter runs fine; only the headers needed to compile against it are missing.

psycopg/psycopgmodule.c:9:10: fatal error: Python.h: No such file or directory
    9 | #include "Python.h"
      |          ^~~~~~~~~~
compilation terminated.
error: command 'gcc' failed with exit status 1

Common causes

Development headers not installed

The base interpreter package does not include Python.h. Compiling any C extension requires the separate dev package (python3-dev on Debian/Ubuntu, python3-devel on RHEL/Fedora).

Headers for the wrong Python version

If you installed python3-dev but build against a different minor version (e.g. a 3.12 from deadsnakes), you need that version’s headers (python3.12-dev).

How to fix it

Install the matching dev headers

# Debian/Ubuntu
apt-get update && apt-get install -y python3-dev
# version-specific
apt-get install -y python3.12-dev
# RHEL/Fedora
dnf install -y python3-devel

Prefer a wheel to skip compiling

If a prebuilt wheel exists for your platform, install it and you never touch Python.h.

pip install --only-binary :all: <package>

How to prevent it

• Bake python3-dev (matching your Python version) into runner images that compile extensions.
• Prefer wheels in CI to avoid needing headers at all.
• Pin Python to a version with wheel coverage for your native dependencies.

Related guides