PyInstaller 5.x打包含sounddevice的Python3.7项目失败求助

问题背景 #

• 基于Python 3.7开发的项目，使用sounddevice==0.4.1时运行完全正常
• 将PyInstaller升级至5.10.1或5.11.0版本后，打包过程出现兼容性错误，当前配套依赖为pyinstaller-hooks-contrib==2022.0
• 核心报错信息：

ValueError: Package 'sounddevice' does not exist or is not a package!
原因：旧版hook-sounddevice.py中使用的get_package_paths函数，无法识别sounddevice 0.4.1的单文件模块结构（它并非标准Python包），且PyInstaller 5.x对模块识别逻辑做了调整，导致冲突。

可行解决方案 #

方案1：升级pyinstaller-hooks-contrib到兼容版本 #

旧版hook库的sounddevice钩子未适配PyInstaller 5.x和sounddevice的模块结构，直接执行以下命令更新：

pip install --upgrade pyinstaller-hooks-contrib

建议升级到2023.0及以上版本，新版钩子已修复该问题。

方案2：自定义本地hook文件（无法升级依赖时使用） #

1. 在项目根目录创建hooks文件夹，新建hook-sounddevice.py文件，写入以下内容：

from PyInstaller.utils.hooks import collect_data_files

# 收集sounddevice运行所需的依赖数据文件
datas = collect_data_files('sounddevice')

2. 打包时指定自定义hook目录：

pyinstaller --additional-hooks-dir=hooks your_main_script.py

或者直接修改项目的spec文件，添加钩子路径：

a = Analysis(
    # 保留原有参数，新增hooks配置
    hooks=['hooks/hook-sounddevice.py'],
    # ... 其他原有参数
)

方案3：降级PyInstaller到兼容版本 #

如果暂时无法升级hook库，可将PyInstaller降级到5.9.0及以下版本，该版本与旧版hook兼容性更好：

pip install pyinstaller==5.9.0

验证方法 #

1. 重新执行打包命令，确认无报错产生
2. 运行生成的EXE程序，测试sounddevice相关功能是否正常工作

内容的提问来源于stack exchange，提问作者Betty Crokker