Linux环境下PyAudio编译报错：Python.h: No such file or directory

问题重现 #

在Linux系统的modulos-proyectos虚拟环境中执行pip install pyaudio，出现编译失败，核心错误日志如下：

(modulos-proyectos) josue@josue-OptiPlex-3010:~/Descargas/portaudio$ pip install pyaudio
Collecting pyaudio
  Using cached PyAudio-0.2.14.tar.gz (47 kB)
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: pyaudio
  Building wheel for pyaudio (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Building wheel for pyaudio (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [19 lines of output]
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build/lib.linux-x86_64-cpython-312
      creating build/lib.linux-x86_64-cpython-312/pyaudio
      copying src/pyaudio/__init__.py -> build/lib.linux-x86_64-cpython-312/pyaudio
      running build_ext
      building 'pyaudio._portaudio' extension
      creating build/temp.linux-x86_64-cpython-312
      creating build/temp.linux-x86_64-cpython-312/src
      creating build/temp.linux-x86_64-cpython-312/src/pyaudio
      x86_64-linux-gnu-gcc -fno-strict-overflow -Wsign-compare -DNDEBUG -g -O2 -Wall -g -fstack-protector-strong -Wformat -Werror=format-security -g -fwrapv -O2 -fPIC -I/usr/local/include -I/usr/include -I/home/josue/Documentos/PythonUniversalModulos/modulos-proyectos/include -I/usr/include/python3.12 -c src/pyaudio/device_api.c -o build/temp.linux-x86_64-cpython-312/src/pyaudio/device_api.o
      In file included from src/pyaudio/device_api.c:1:
      src/pyaudio/device_api.h:7:10: fatal error: Python.h: No such file or directory
          7 | #include "Python.h"
            |          ^~~~~~~~~~
      compilation terminated.
      error: command '/usr/bin/x86_64-linux-gnu-gcc' failed with exit code 1
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for pyaudio
Failed to build pyaudio
ERROR: Could not build wheels for pyaudio, which is required to install pyproject.toml-based projects

针对性解决方案 #

从日志可见你使用的是Python 3.12，以下步骤按该版本适配：

• 第一步：安装对应版本的Python开发包
  Python.h属于Python编译依赖的头文件，必须安装对应版本的开发包才能被编译器找到：

sudo apt-get update && sudo apt-get install python3.12-dev

（若为RHEL/CentOS系列系统，替换为sudo dnf install python3.12-devel）

• 第二步：重新尝试安装
  安装完开发包后，重新激活虚拟环境并执行安装命令：

source /home/josue/Documentos/PythonUniversalModulos/modulos-proyectos/bin/activate
pip install pyaudio

• 第三步：手动指定头文件路径（若第二步无效）
  如果编译器仍无法定位Python.h，安装时强制指定系统Python 3.12的头文件目录：

pip install pyaudio --global-option=build_ext --global-option="-I/usr/include/python3.12"

• 备选方案：通过系统包直接安装
  若不需要虚拟环境完全隔离，可先在系统层面安装PyAudio，再创建虚拟环境时允许访问系统站点包：

sudo apt-get install python3-pyaudio
# 重新创建带系统站点包访问权限的虚拟环境（原有环境可按需备份）
python3.12 -m venv --system-site-packages modulos-proyectos
source modulos-proyectos/bin/activate

内容的提问来源于stack exchange，提问作者Jeferson Escobar