PyAudio安装失败求助：跨Linux发行版的编译与导入错误

一、Linux Mint 21.3 x86_64下的编译与导入问题 #

1. 编译阶段：portaudio.h找不到错误 #

尝试安装PyAudio用于SpeechRecognition时，出现编译错误，完整输出如下：

Collecting PyAudio
Using cached PyAudio-0.2.14.tar.gz (47 kB)
Installing build dependencies: started
Installing build dependencies: finished with status 'done'
Getting requirements to build wheel: started
Getting requirements to build wheel: finished with status 'done'
Preparing metadata (pyproject.toml): started
Preparing metadata (pyproject.toml): finished with status 'done'
Building wheels for collected packages: PyAudio
Building wheel for PyAudio (pyproject.toml): started
Building wheel for PyAudio (pyproject.toml): finished with status 'error'
Failed to build PyAudio
error: subprocess-exited-with-error

× Building wheel for PyAudio (pyproject.toml) did not run successfully.
│ exit code: 1
╰─> [18 lines of output]
running bdist_wheel
running build
running build_py
creating build
creating build/lib.linux-x86_64-cpython-311
creating build/lib.linux-x86_64-cpython-311/pyaudio
copying src/pyaudio/__init__.py -> build/lib.linux-x86_64-cpython-311/pyaudio
running build_ext
building 'pyaudio._portaudio' extension
creating build/temp.linux-x86_64-cpython-311
creating build/temp.linux-x86_64-cpython-311/src
creating build/temp.linux-x86_64-cpython-311/src/pyaudio
x86_64-unknown-linux-gnu-gcc -Wsign-compare -DNDEBUG -g -fwrapv -O3 -Wall -O2 -pipe -g -Wp,-D_FORTIFY_SOURCE=2 -Wp,-D_GLIBCXX_ASSERTIONS -fexceptions -fstack-protector-strong -grecord-gcc-switches -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection -fno-omit-frame-pointer -O2 -pipe -g -Wp,-D_FORTIFY_SOURCE=2 -Wp,-D_GLIBCXX_ASSERTIONS -fexceptions -fstack-protector-strong -grecord-gcc-switches -fasynchronous-unwind-tables -fstack-clash-protection -fcf-protection -fno-omit-frame-pointer -fPIC -I/usr/local/include -I/usr/include -I/usr/include/python3.11 -I/usr/include/x86_64-linux-gnu/python3.11 -c src/pyaudio/device_api.c -o build/temp.linux-x86_64-cpython-311/src/pyaudio/device_api.o
src/pyaudio/device_api.c:9:10: fatal error: portaudio.h: No such file or directory
9 | #include "portaudio.h"
|          ^~~~~~~~~~~~~
compilation terminated.
error: command '/usr/bin/x86_64-unknown-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
ERROR: Could not build wheels for PyAudio, which is required to install pyproject.toml-based projects

已安装portaudio19-dev，且/usr/include/portaudio.h文件存在，尝试pip install PyAudio、pip install --user PyAudio均失败，使用PyCharm 2024.1.1开发环境。

2. 虚拟环境导入阶段：libportaudio.so.2找不到错误 #

在系统终端执行python3.11 -m pip install PyAudio安装成功后，在PyCharm虚拟环境中通过本地wheel包安装：

source /.venv/bin/activate 
pip install /home/username/.cache/pip/wheel/something/something/something/something/PyAudio-0.2.14-cp311-cp311-linux_x86_64.whl

但导入PyAudio时出现错误：

ImportError: libportaudio.so.2: cannot open shared object file: No such file or directory
Could not import the PyAudio C module 'pyaudio._portaudio'.

二、Arch Linux下PyPy3安装PyAudio的编译错误 #

切换到Arch Linux后，使用pypy3 -m pip install pyaudio出现新的编译错误：

[thedisk@archlinux portaudio]$ pypy3 -m pip install pyaudio
Defaulting to user installation because normal site-packages is not writeable
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
  ╰─> [26 lines of output]
      running bdist_wheel
      running build
      running build_py
      creating build
      creating build/lib.linux-x86_64-pypy310
      creating build/lib.linux-x86_64-pypy310/pyaudio
      copying src/pyaudio/__init__.py -> build/lib.linux-x86_64-pypy310/pyaudio
      running build_ext
      building 'pyaudio._portaudio' extension
      creating build/temp.linux-x86_64-pypy310
      creating build/temp.linux-x86_64-pypy310/src
      creating build/temp.linux-x86_64-pypy310/src/pyaudio
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/device_api.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/device_api.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/host_api.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/host_api.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/init.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/init.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/mac_core_stream_info.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/mac_core_stream_info.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/main.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/main.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/misc.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/misc.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/stream.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/stream.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/stream_io.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/stream_io.o
      gcc -pthread -DNDEBUG -O2 -fPIC -I/usr/local/include -I/usr/include -I/opt/pypy3/include/pypy3.10 -c src/pyaudio/stream_lifecycle.c -o build/temp.linux-x86_64-pypy310/src/pyaudio/stream_lifecycle.o
      src/pyaudio/stream_lifecycle.c: In function ‘PyAudio_OpenStream’:
      src/pyaudio/stream_lifecycle.c:249:55: error: ‘PyThreadState’ {aka ‘struct _ts’} has no member named ‘thread_id’
        249 |   stream->context.main_thread_id = PyThreadState_Get()->thread_id;
            |                                                       ^~
      error: command '/usr/bin/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: ERROR: Failed to build installable wheels for some pyproject.toml based projects (pyaudio)

对应解决方案 #

针对Linux Mint环境 #

1. 编译找不到portaudio.h的问题
   手动指定头文件和库路径强制编译：

   pip install PyAudio --global-option="build_ext" --global-option="-I/usr/include" --global-option="-L/usr/lib/x86_64-linux-gnu"
   

   先确保系统依赖完整：

   sudo apt install build-essential libasound2-dev portaudio19-dev libportaudio2 libportaudiocpp0
   

2. 虚拟环境导入库失败问题

   • 临时生效：在终端执行以下命令后再运行程序

     export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
     

   • 永久生效：在虚拟环境的激活脚本.venv/bin/activate末尾添加上述export命令；或在PyCharm运行配置中设置环境变量LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu。

针对Arch Linux+PyPy3环境 #

这个错误是PyAudio源码与PyPy的Python API不兼容导致的——PyPy的PyThreadState结构没有thread_id成员，而CPython存在该成员。解决方式：

1. 切换到CPython安装预编译包
   PyAudio对CPython支持更完善，直接安装官方仓库的预编译包：

   sudo pacman -S python-pyaudio
   

2. 修改PyAudio源码兼容PyPy
   若必须使用PyPy，手动修改PyAudio源码后本地编译：

   • 下载源码：git clone https://github.com/jleb/pyaudio.git && cd pyaudio
   • 打开src/pyaudio/stream_lifecycle.c，找到第249行，替换为兼容代码：

     #include <pthread.h>
     // ...
     stream->context.main_thread_id = (unsigned long)pthread_self();
     

   • 本地编译安装：pypy3 -m pip install .

3. 安装AUR的PyPy兼容包
   使用yay安装AUR中针对PyPy的PyAudio包：

   yay -S pypy3-pyaudio
   

内容的提问来源于stack exchange，提问作者For Accounts