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

The C compiler tried to include Python.h while building a Cython or C extension and could not find it. That header ships with the Python development package (python3-dev / python3-devel), which is missing on the runner.

What this error means

The compile stops with "fatal error: Python.h: No such file or directory" and "compilation terminated", usually while building a C extension or Cythonized module.

mypkg/fast.c:17:10: fatal error: Python.h: No such file or directory
   17 | #include "Python.h"
      |          ^~~~~~~~~~
compilation terminated.

Common causes

Python dev headers not installed

Python.h is part of python3-dev (Debian/Ubuntu) or python3-devel (RHEL). A base image with only the runtime lacks it.

Headers for the wrong Python version

If the runner has 3.11 but only 3.10 dev headers are installed, the include path for the active interpreter is still missing.

How to fix it

Install the matching dev headers

1. Install python3-dev (or python3.X-dev) before building.
2. Make sure the version matches the active interpreter.
3. Re-run the compile.

- run: sudo apt-get update && sudo apt-get install -y python3-dev

Use setup-python which bundles headers

The setup-python action provides the headers for the version it installs, avoiding a separate apt step.

- uses: actions/setup-python@v5
  with: { python-version: '3.11' }

How to prevent it

• Install dev headers matching the build interpreter.
• Prefer setup-python, which includes headers, over bare base images.
• Build extensions in CI so a missing header fails fast.

Related guides