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

A C extension include line #include <Python.h> could not be resolved because the Python development headers are not installed. The compiler aborts with a fatal error.

What this error means

The wheel build fails with "fatal error: Python.h: No such file or directory" during compilation, typically on slim images that have the interpreter but not its dev package.

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

Common causes

The python3-dev package is missing

The runtime interpreter does not include Python.h; the headers ship separately in python3-dev / python3-devel.

Headers do not match the active interpreter

Installing python3-dev for the system Python while building against a different version (pyenv, setup-python) leaves the headers unmatched.

How to fix it

Install the matching dev headers

1. Install the dev package for the exact Python version you build against.
2. Re-run the build so the compiler finds Python.h.

# Debian/Ubuntu - match your version, e.g. 3.12
sudo apt-get install -y python3.12-dev
# Fedora/RHEL
sudo dnf install -y python3-devel

Avoid the compile with a prebuilt wheel

A manylinux wheel bundles the compiled extension and needs no headers.

pip install --only-binary=:all: simplejson

How to prevent it

• Install the version-matched python3.X-dev package before compiling extensions.
• Prefer binary wheels for compiled dependencies.
• Keep dev headers aligned with the interpreter you actually build against.

Related guides