Maaz Zindani

Loading the index…

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

gcc cannot find Python.h although Python is installed

Errorfatal error: Python.h: No such file or directory

Short answer

Python.h ships in a separate development package, not with the interpreter. On Ubuntu and Debian install python3-dev, which brings in the headers for your Python version. If the file exists but gcc still fails, you are compiling against a different Python than the one that owns the headers.

  • Applies to Ubuntu 24.04, Python 3.12, gcc 13
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the system whether the header exists at all for the Python you run.

    python3 --version
    ls /usr/include/python3*/Python.h
  2. 2Match what you see, then jump to its fix

    1. 1ls prints 'No such file or directory' for /usr/include/python3*/Python.hThe development headers are not installedFix
    2. 2Python.h exists under one prefix, but the build uses another Python (a custom build, a second install)gcc is not pointed at the include directory of the Python you useFix

What does the error look like?

  • fatal error: Python.h: No such file or directory
  • #include <Python.h>
  • compilation terminated.

Cause 1 of 2

The development headers are not installed

1Check

Ubuntu keeps the headers in libpython3.12-dev (for Python 3.12). Its file list contains /usr/include/python3.12/Python.h. A minimal server or container image has the interpreter but not this package.

dpkg -l | grep -E 'python3-dev|libpython3.*-dev'

2Fix

Install python3-dev. It is the package that depends on the matching libpython3-dev, which in turn pulls the headers for your Python version.

sudo apt update
sudo apt install python3-dev

3Verify

The header now exists and a pip build that needs it goes through.

ls /usr/include/python3*/Python.h

Confirmed by packages.ubuntu.com

Did this fix it?

Cause 2 of 2

gcc is not pointed at the include directory of the Python you use

1Check

The Python docs say each Python install has its own python-config script that prints the compiler flags, and that you should call it by absolute path when several installs exist.

which python3
/usr/bin/python3-config --cflags

2Fix

Pass the flags from the config script of the same Python that will load the module.

gcc $(/usr/bin/python3-config --cflags) -c module.c -o module.o

3Verify

The compile step runs past the #include line without the fatal error.

ls -l module.o

Confirmed by docs.python.org

Did this fix it?

How do I stop it coming back?

  • Add python3-dev to the apt install line of every Dockerfile or CI image that compiles Python packages.
  • Install the gcc toolchain and the headers together, so a missing piece shows up at image build, not at deploy.
  • Call python3-config by absolute path when more than one Python exists on the machine.

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.