PyQt5与qtpy兼容性问题：PyInstaller打包后运行报错求解

环境与操作 #

• 脚本文件 test_script.py 内容：

from PyQt5 import QtWidgets, QtCore, QtGui

• 操作流程：
  1. 执行 pip install qtpy 安装qtpy依赖
  2. 运行 pyinstaller --onedir test_script.py 打包脚本
  3. 进入 dist/test_script 目录启动 test_script.exe

报错信息 #

Traceback (most recent call last):
  File "test_script.py", line 1, in <module>
ImportError: DLL load failed: The specified module could not be found.
[7508] Failed to execute script 'test_script' due to unhandled exception!

初步排查 #

• 卸载qtpy（执行 pip uninstall qtpy）后重新打包，exe可正常运行
• qtpy是某个qtwidgets类库的依赖项，临时解决方案为修改该类库代码：将qtpy替换为PyQt5，Signal替换为pyqtSignal，Slot替换为pyqtSlot，并重命名为extra_qtwidgets，但需要通用解决方案。

方案1：打包时排除qtpy模块 #

直接通过PyInstaller的--exclude-module参数排除qtpy，避免其干扰PyQt5的DLL打包，命令如下：

pyinstaller --onedir --exclude-module qtpy test_script.py

此方法无需修改依赖类库，因为你的脚本本身不直接依赖qtpy，排除后不影响原类库的功能（只要运行环境中PyQt5正常）。

方案2：强制指定QT_API环境变量 #

qtpy作为Qt抽象层，会根据QT_API环境变量选择底层Qt绑定。打包前设置变量强制使用PyQt5：

• Windows命令行：

set QT_API=pyqt5
pyinstaller --onedir test_script.py

• Linux/macOS终端：

export QT_API=pyqt5
pyinstaller --onedir test_script.py

这样qtpy会优先绑定PyQt5，避免打包时引入不兼容的DLL路径。

方案3：手动修改spec文件调整依赖 #

若前两种方法无效，可生成并修改spec文件来精准控制依赖：

1. 生成spec文件：

pyinstaller --onedir test_script.py --specpath .

2. 打开test_script.spec，在Analysis部分添加PyQt5的隐式依赖并排除qtpy：

a = Analysis(
    ['test_script.py'],
    pathex=[],
    binaries=[],
    datas=[],
    hiddenimports=['PyQt5.QtWidgets', 'PyQt5.QtCore', 'PyQt5.QtGui'],
    hookspath=[],
    hooksconfig={},
    runtime_hooks=[],
    excludes=['qtpy'],
    win_no_prefer_redirects=False,
    win_private_assemblies=False,
    cipher=block_cipher,
    noarchive=False,
)

3. 基于修改后的spec文件重新打包：

pyinstaller test_script.spec

内容的提问来源于stack exchange，提问作者Chris P