Python.h Not Found Despite python3-dev Installed in CI

The compiler cannot find Python.h even though you installed dev headers - because the headers you installed are for a different interpreter than the one building the extension. The header set must match the building Python’s minor version.

What this error means

A C-extension build fails with fatal error: Python.h: No such file or directory despite python3-dev (or python3.X-dev) being installed. The mismatch is between the headers’ Python version and the interpreter pip is building against.

Build output

building 'wrapt._wrappers' extension
wrapt/_wrappers.c:1:10: fatal error: Python.h: No such file or directory
 #include <Python.h>
          ^~~~~~~~~~
compilation terminated.

Common causes

Dev headers for a different Python version

You installed python3-dev (system 3.11) but the build uses a pyenv/venv 3.12 interpreter whose headers are elsewhere, so the matching Python.h is not on the include path.

A pyenv/from-source interpreter without staged headers

A from-source interpreter keeps its headers under its own prefix. If that prefix is not on the include path, the system python3-dev does not help.

How to fix it

Install dev headers for the exact building Python

Match the header package to the interpreter pip uses.

Terminal

python -c "import sys; print(sys.version)"   # which interpreter builds
# Debian/Ubuntu: install the matching dev package
apt-get install -y python3.12-dev

Confirm the include path points at the right prefix

Run python -c "import sysconfig; print(sysconfig.get_path('include'))".
Ensure that directory contains Python.h; if not, the headers for this interpreter are missing.
For pyenv builds, reinstall the interpreter so its headers are present under its prefix.

How to prevent it

Install the dev headers for the exact interpreter that compiles extensions.
Prefer wheels so no headers are needed at all.
Keep the building Python and its -dev package on the same minor version.