Fix “Python.h: No such file or directory”

The compiler cannot find the Python C API headers for the interpreter you are building against. The headers may be missing, or the build may be using the wrong include path. Check the interpreter before installing another Python development package.

Identify the active interpreter and header directory

python -m pip --version
python -c "import sys, sysconfig; print(sys.executable); print(sys.version); print(sysconfig.get_path('include'))"

Look for Python.h in that include directory. If it exists, inspect the failing compiler command: it should include the matching -I path. An embedding application may also require Python library/linker flags, which are separate from finding a header.

Install headers for a distribution-managed Python

Choose the command for the distribution and Python installation you actually use:

# Debian or Ubuntu: distribution-default Python
sudo apt update
sudo apt install python3-dev

# Fedora or current RHEL-family distributions
sudo dnf install python3-devel

# Older distributions that use yum
sudo yum install python3-devel

# Alpine: distribution-managed Python
apk add python3-dev

A non-default interpreter may need a matching versioned package, such as python3.11-dev, if your repositories provide it. Match the Python version and architecture. You may also need a C/C++ compiler and library-specific development packages.

This often appears during a source build triggered by pip install, or while compiling a C/C++ application that embeds Python. A compatible binary wheel can avoid a local extension build, when the package provides one for your platform.

Windows and macOS

A Windows build can also have a missing or incorrect header path; do not assume every failure is a compiler problem. A normal full Python installation includes headers, while some minimal or embedded distributions differ. Check that installation and use a compatible Microsoft C++ build toolchain for extensions that need it.

On macOS, python.org and Homebrew installations normally provide their own headers. Xcode Command Line Tools supply compiler tooling, not a replacement for the matching Python headers. Check the interpreter's include directory first, then install the compiler tools if they are missing.

Virtual environments and containers

A virtual environment usually relies on headers belonging to its base interpreter. If the interpreter came from pyenv or a custom build, installing the operating system's python3-dev may target an entirely different Python.

Official Python container images, including slim and Alpine variants, commonly install Python under /usr/local with its headers. Their reduced size does not imply that Python.h is absent. Check the actual image and its compiler command before adding distribution packages. Installing Alpine's or Debian's Python headers can introduce a second, mismatched interpreter.

For compiled dependencies, a multi-stage build can keep build tools out of the final image. Preserve the extension's required runtime libraries and use compatible Python versions and system libraries across stages.

FAQ

The development package is installed. Why does compilation still fail? Compare its version with python -m pip --version, the include directory from sysconfig, and the compiler's arguments. The build may be targeting another interpreter or ignoring the correct path.

Should I copy Python.h into the project? No. It depends on other headers and the interpreter's configuration. Fix the installation or build flags instead.

References

• docs.python.org documentation
• docs.python.org documentation
• github.com documentation
• github.com documentation