gcc cannot find Python.h although Python is installed
fatal error: Python.h: No such file or directoryShort 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.
Fix it fast
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.h2Match what you see, then jump to its fix
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-dev3Verify
The header now exists and a pip build that needs it goes through.
ls /usr/include/python3*/Python.hConfirmed by packages.ubuntu.com
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 --cflags2Fix
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.o3Verify
The compile step runs past the #include line without the fatal error.
ls -l module.oConfirmed by docs.python.org
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix