编译报错 "fatal error: Python.h: No such file or directory" 怎么解决？

原因：编译器找不到当前目标 Python 对应的开发头文件，可能缺失，也可能版本或 include 路径不匹配（C 扩展编译需要）。解决：Ubuntu/Debian 执行 sudo apt install python3-dev；CentOS/RHEL 执行 sudo yum install python3-devel（或 dnf）；装完重新编译即可。

各系统的安装命令

# Ubuntu / Debian
sudo apt update && sudo apt install python3-dev

# CentOS / RHEL / Fedora
sudo yum install python3-devel
# 或新版本：
sudo dnf install python3-devel

# Alpine
apk add python3-dev

注意版本匹配：如果你用的是 Python 3.11，有些发行版需要指定版本包名，如 apt install python3.11-dev。先用 python3 --version 确认。

什么时候会遇到这个错误

• pip install 某些需要编译 C 扩展的包（如 psycopg2、numpy 旧版本源码编译、uWSGI）；
• 自己编译嵌入 Python 的 C/C++ 程序。

Windows 和 macOS

• Windows：也可能缺头文件或 include 路径错误，缺编译器是另一类问题——安装 Microsoft C++ Build Tools；并确保装 Python 时勾选了开发头文件（默认包含）。
• macOS：官方 python.org 安装包和 Homebrew 的 Python 都自带头文件，一般不会出现；若出现，先用 python3 -c 'import sysconfig; print(sysconfig.get_path("include"))' 检查实际头文件路径；Xcode Command Line Tools 提供编译工具，不会自动补齐所有 Python 安装的匹配头文件。

常见问题（FAQ）

Q：装了 python3-dev 还是报错？
A：确认 pip 对应的 Python 版本和 dev 包版本一致（pip -V 看绑定的解释器）；多版本共存时可能需要 python3.x-dev。

Q：虚拟环境里需要装吗？
A：dev 包装在系统层，虚拟环境复用系统解释器的头文件。但如果用 pyenv 等自编译的 Python，头文件在 pyenv 目录里，pip 应能自动找到。

Q：Docker 里报错怎么办？
A：官方 python 镜像的 slim/Alpine 变体通常也包含 /usr/local 下自编译 Python 的头文件；先检查目标解释器 sysconfig 的 include 路径和缺少的编译器/系统库。盲装发行版 python3-dev 可能对应另一套 Python，不能保证匹配。