Ubuntu下PyInstaller打包PyQt5+qpageview程序PDF显示空白问题求助

问题根源 #

qpageview依赖Qt内置的PDF渲染插件（libqpdf.so），但PyInstaller默认不会自动收集这类Qt插件。打包后的程序找不到渲染引擎，导致PDF内容无法渲染，只显示空白的Page View。

具体解决步骤 #

1. 代码中指定Qt插件搜索路径 #

在初始化QApplication前，添加代码设置Qt插件路径，确保程序能找到打包后的插件：

import os
from PyQt5.QtCore import QCoreApplication

# 设置Qt插件路径，适配打包后的目录结构
plugin_dir = os.path.join(os.path.dirname(QCoreApplication.applicationDirPath()), "plugins")
os.environ["QT_PLUGIN_PATH"] = plugin_dir

2. 打包时强制包含PDF插件 #

找到你虚拟环境中Qt PDF插件的目录，通常路径为：
/path/to/your/venv/lib/python3.x/site-packages/PyQt5/Qt5/plugins/pdf

用PyInstaller的--add-data参数将该目录打包进程序，修改打包命令为：

pyinstaller -F --add-data "/path/to/venv/PyQt5/Qt5/plugins/pdf:plugins/pdf" src/main.py

如果不确定插件路径，可在虚拟环境中执行以下命令获取：

python -c "from PyQt5.QtCore import QLibraryInfo; print(QLibraryInfo.location(QLibraryInfo.PluginsPath))"

在输出的路径下找到pdf子目录即可。

3. 确认PDF文件路径有效性 #

运行打包后的程序时，确保pyqt.pdf在当前工作目录，或者改用绝对路径加载PDF避免路径问题：

import os
# 获取当前目录下的PDF绝对路径
pdf_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "pyqt.pdf")
v.loadPdf(pdf_path)

4. 调试排查（可选） #

如果仍未解决，可开启PyInstaller调试模式查看插件加载日志：

pyinstaller -F --debug=imports --add-data "/path/to/pdf/plugins:plugins/pdf" src/main.py

运行dist/main时，会输出详细的模块加载信息，检查是否有QPDF插件加载失败的提示。

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