PyQt5搭配QPageViewer开发时安装python-poppler-qt5依赖报错

你碰到的这个报错本质是两个核心问题：

1. python-poppler-qt5没有官方Windows预编译包，pip默认拉取源码包本地编译，编译时找不到Qt的qmake构建工具就会直接报错
2. 这个包对PyQt5、sip、pyqt-builder的版本匹配要求极其严格，版本差一点就会出现你看到的sipbuild.api属性缺失的报错，随便升级sip或者装最新版PyQt5百分百编不过

别硬怼源码编译，直接装匹配版本的预编译包：

• 第一步：先清干净虚拟环境里装冲突的包

pip uninstall -y PyQt5 PyQt5-Qt5 PyQt5-sip sip pyqt-builder python-poppler-qt5 python-qt5

• 第二步：安装版本严格匹配的PyQt5基础组件，别装最新版

pip install PyQt5==5.15.10 PyQt5-sip==12.13.0

• 第三步：下载对应你Python版本、系统位数的python-poppler-qt5预编译wheel包，选21.3.0版本跟你刚才装的PyQt5版本对应，Python3.9就选带cp39-win_amd64标识的包，Python3.10就选cp310-win_amd64的，下载完直接本地安装：

pip install 你下载的whl文件的本地完整路径

装完直接导入验证就行，不会再报构建错误。

如果你一定要用pip在线安装，必须先把编译环境配全，缺一个都会报错：

• 安装对应5.15版本的Qt5开发环境，安装时必须勾选MinGW编译组件，把qmake.exe所在的目录加到系统PATH环境变量，终端执行qmake -v能正常返回版本号才算配置生效
• 不要升级sip到最新版，固定安装PyQt5-sip==12.13.0、pyqt-builder==1.15.1，版本高了就会出现你碰到的属性缺失报错
• 安装时跳过缓存，执行命令：

pip install python-poppler-qt5==21.3.0 --no-cache-dir

你要实现的侧边可滚动PDF展示功能根本不用死磕QPageViewer，有两个零编译麻烦的替代方案，稳定性更好：

• 方案1：用PyMuPDF（fitz）自行渲染
  只需要装两个包：pip install pymupdf PyQt5，用PyMuPDF把PDF每页渲染成图片转成QPixmap，放到QScrollArea的垂直布局里就行，滚动、缩放逻辑自己写也就几十行代码，没有任何Qt绑定的版本冲突问题，渲染速度比poppler还快。
• 方案2：用PyQt5自带的QtPdf模块
  PyQt5 5.15及以上版本自带QtPdf、QtPdfWidgets模块，不需要额外装poppler相关依赖，直接导入QPdfDocument、QPdfView类，把QPdfView嵌入你的侧边栏区域就行，原生支持滚动、页码跳转、缩放，比第三方封装的QPageViewer Bug少很多。

• 装python-poppler没用，这个是GTK生态的poppler绑定，跟Qt的poppler绑定完全不兼容
• 装python-qt5是conda源的老旧废弃包，跟pip源的PyQt5文件冲突，必然搞坏原有PyQt5环境
• 切换Python3.9/3.10、换PySide都解决不了问题，核心矛盾是依赖版本不匹配+缺编译环境，换解释器或者换Qt绑定只是重复踩坑

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