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

原因：系统没有安装 Python 的开发头文件（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：不是 Python.h 的问题，而是缺编译器——安装 Microsoft C++ Build Tools；并确保装 Python 时勾选了开发头文件（默认包含）。
• macOS：官方 python.org 安装包和 Homebrew 的 Python 都自带头文件，一般不会出现；若出现，检查 xcode-select --install 是否装过。

常见问题（FAQ）

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

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

Q：Docker 里报错怎么办？
A：官方 python:3.x 镜像已含头文件；python:3.x-slim/alpine 精简镜像没有，需在 Dockerfile 中 apt install python3-dev（slim）或 apk add python3-dev（alpine），编译完成后可在多阶段构建中丢弃。