[Fix] gcc – fatal error: Python.h: No such file or directory

By /
Gcc Fatal Error Python H No Such File Or Directory

Tried building a Python C extension or installing a Python package with native code and saw this frustrating error message?

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

This error occurs because the compiler cannot find the Python developer files it needs to build the extension or package. But don’t worry – in most cases, it can be easily fixed!

So if you’ve pulled your hair out over “Python.h: No such file or directory”, read on!

Also read: [Fix] env: python: No such file or directory” Error in Xcode

Why “Python.h: No such file or directory” Happens

When you build Python C extensions or install Python packages containing C code, the C compiler needs to be pointed to the Python developer files. These files provide access to Python’s C API and definitions needed to build Python-aware extensions.

The Python.h file is the major header that gives access to core Python data structures and functions. If the compiler can’t find it, you’ll see the “fatal error” above.

By default, your system Python install doesn’t always include these developer files and headers. So when you try to build extensions/packages, the compiler throws the error because it lacks those file definitions.

Installing the Python Developer Files

The good news is this issue is usually fixed by installing the Python dev/header files for your distribution.

Here are solutions for some common platforms:

Ubuntu/Debian

Install the python-dev or python3-dev packages:

# For Python 2.x
sudo apt install python-dev   

# For Python 3.x 
sudo apt install python3-dev

Note: The dev packages above don’t cover all minor versions of Python 3. If you use a specific one like 3.8, install its dev package instead:

sudo apt install python3.8-dev

RHEL/CentOS

Use yum to install the developer file RPMs:

# For Python 2.x
sudo yum install python-devel

# For Python 3.x
sudo yum install python3-devel

As on Debian, install a specific version’s package if needed:

sudo yum install python3.12-devel

Fedora

On Fedora, the dnf command is used:

# For Python 2.x
sudo dnf install python2-devel  

# For Python 3.x
sudo dnf install python3-devel

openSUSE

Use zypper to install development files:

sudo zypper in python-devel    # For Python 2.x
sudo zypper in python3-devel   # For Python 3.x

And so on for other common distros – use your package manager to bring in the Python dev files.

Specifying the Python Version

As shown above, developer header packages are often tied to specific Python versions. Installing the generic python-dev or python3-dev may not be enough if you use, say, Python 3.12 instead of the system default.

Always check your active Python version and install the matching dev package.

For example if you’re on Ubuntu with both Python 2.7 and 3.12 installed, make sure you apt install the dev headers for the Python runtime being used for compiling extensions or building packages.

Also read: How to Read CSV with Headers Using Pandas?

Other Methods for Pointing to Python Headers

Sometimes the developer packages alone don’t fully resolve the issues. Here are two other techniques:

python-config

Python comes with a script called python-config that outputs compiler and linker flags for building extensions against a specific Python version.

Here’s an example using it to get the include dirs and library link flags:

gcc -c mymodule.c $(python3.8-config --includes) 
gcc -o mymodule mymodule.o $(python3.8-config --ldflags)

This method works well for pointing the compiler to headers of non-system Python installs.

Export Include Path

You can also manually export the include path with the correct Python.h location:

export C_INCLUDE_PATH=/opt/python/3.7.1/include/python3.7m

Then compile as usual, with the compiler now able to find the headers.

Summary

A few points to remember:

  • The “Python.h: No such file or directory” compiler error happens because Python developer files are missing
  • On most systems, installing the python-dev or python3-dev packages resolves it
  • Sometimes version-specific dev packages are needed instead
  • The python-config script and export workarounds are useful alternatives

With the developer files installed or the header path exported correctly, you can successfully build C extensions and install Python packages requiring compilation on Linux systems.

I hope this guide gives you a solid understanding of why the error occurs and how to fix it when building Python native code!

Reference: StackOverflow