1. 装之前先想清楚这三件事版本选择、工具链、下载源先说个挺常见的事很多人拿到 PyQt5 安装教程第一步就去pip install PyQt5装了半小时装不上装上了打开 PyCharm 又找不到 Qt Designer找到 Designer 画完界面又不知道该怎么转成 Python 代码。折腾一整天最后卡在“为啥我的窗口弹不出来”上。这种体验特别劝退但其实整条链路捋顺了从零到能跑第一个窗口二十分钟足够了。在动手之前有三件容易被忽略的事值得先花两分钟想清楚能帮你少走很多弯路。1.1 Python 版本别追新稳定比什么都重要很多新手上来就装最新版 Python结果装 PyQt5 时遇到各种“不支持”“编译失败”的报错其实多半不是 PyQt5 的问题而是 Python 版本太新PyQt5 的预编译包还没跟上。以我个人的经验Python 3.8 到 3.11 之间随便选一个都行目前 PyQt5 对这几个版本的 wheel 预编译包支持最稳定。Python 3.12 及以上也能用但个别扩展库可能还没适配没必要为了尝鲜给自己挖坑。如果你电脑上还没装 Python直接去官网下载 Python 3.10 或 3.11 的 64 位安装包装的时候务必勾选“Add Python to PATH”这个选项不勾后面pip命令会找不到很多人明明装了 Python 却提示pip 不是内部或外部命令基本都是这个原因。另外强调一点安装路径不要带中文和空格。C:\Python311这样最省心。以前见过有人装在D:\软件\Python下面PyQt5 工具链里的某些组件对中文路径处理不好跑起来莫名其妙报错排查到最后才发现是路径问题。1.2 PyCharm 社区版就够了专业版这事说清楚PyCharm 分为社区版Community和专业版Professional。很多人一听“专业版”就觉得功能强、必须装然后满世界找激活码这其实是没必要的。做 PyQt5 开发社区版完全够用它自带 Python 解释器配置、虚拟环境管理、代码补全、运行调试这些核心功能而专业版多出来的远程开发、数据库工具、Django/Flask 等 Web 框架支持跟 PyQt5 桌面开发关系不大。换句话说你装专业版用到的功能社区版基本都有。如果你确实因为其他原因需要专业版建议通过正规渠道获取授权或者直接使用官方提供的免费试用期。满网搜的那些“激活码”“破解补丁”一个是安全性没保障另一个是很多写着“永久”的其实用几天就失效折腾半天省不了什么反而浪费时间。下载地址就是 JetBrains 官网选 Community 版本下载安装包一路 Next 就行。安装时建议勾选“创建桌面快捷方式”和“添加到 PATH”后面命令行里直接敲pycharm能打开方便一些。1.3 确定用 pip 装还是用 Anaconda 环境现在装 PyQt5主流是两种途径纯 pip 安装如果你是普通 Python 环境直接pip install PyQt5就完事。这也是本教程的主线最简单直接。Anaconda 环境下安装如果你平时用 Anaconda 做科学计算PyQt5 也可以装在 conda 环境里。优点是 conda 会自动处理一些底层依赖缺点是要额外装 Anaconda对只想写个桌面工具的人来说有点重。我的建议是没有 Anaconda 就别专门为了 PyQt5 装一个。PyQt5 本身依赖很少pip 一把梭完全能搞定。如果你已经装了 Anaconda那就在 Anaconda Prompt 里创建一个新环境再装避免和基础环境里的包打架。1.4 下载源先换好不然第一步就卡死PyQt5 本体加工具链全部装完体积大概在 200MB 左右从 PyPI 官方源下载在国内很多时候慢到怀疑人生甚至直接超时失败。所以动手之前先把 pip 的下载源切到清华或者阿里云的镜像。命令很简单pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple切完之后再装 PyQt5速度会是另一个量级。这一步属于一劳永逸的配置以后装任何 Python 包都用得上。2. 安装 PyQt5 本体命令就三条但每条都有讲究环境理顺了下面进入正题。PyQt5 的安装命令看起来很简单但里面有几个细节装的时候不注意后面配置 PyCharm 时就会出问题。2.1 先确认 Python 环境和 pip 状态打开命令行快速确认三件事python --version pip --version where pythonpython --version确认版本号比如Python 3.11.x。pip --version确认 pip 可用。如果提示没找到 pip回到 Python 安装包重新运行一次把安装选项里的 pip 组件勾上。where python看看 Python 路径里有没有带空格或者中文有的话建议重装别嫌麻烦后面省的事比现在麻烦多了。这里多说一句如果你电脑上装了 Microsoft Store 版本的 Pythonwhere python可能会列出好几个路径推荐用官方 python.org 的安装路径避免后续解释器混乱。2.2 一条命令装齐三个组件PyQt5 的安装我建议一次性装三个包pip install PyQt5 PyQt5-tools PyQt5-sip为什么要三个一起装PyQt5核心库提供 Qt 的各种模块。PyQt5-tools包含 Qt Designer、Qt Assistant、Qt Linguist 等桌面工具。这个很容易被漏掉没有它PyCharm 里就找不到图形界面设计器。PyQt5-sipPyQt5 的底层绑定依赖一般安装 PyQt5 时会自动带上但手动明确装一次可以避免某些环境下版本不对应的报错。如果你是在 Anaconda 环境里操作也可以用conda install pyqt5 pyqt5-tools效果类似但 conda 源里的版本可能比 PyPI 旧一些。装完之后检查一下装到了哪里pip show PyQt5 PyQt5-tools记录下Location字段的输出路径后面配置 Qt Designer 时要用。2.3 Microsoft Visual C 14.0 is required 报错怎么处理很多人在安装时遇到这个经典报错error: Microsoft Visual C 14.0 is required. Get it with Microsoft Visual C Build Tools先别慌这个报错有两个层面的情况第一种情况你安装的是较新版本的 PyQt55.15 系列理论上官方提供了编译好的 wheel不应该再要求编译。如果此时出现这个错多半是 pip 版本太老、无法识别当前平台的 wheel 文件下载了源码包进而触发编译。解决办法是先把 pip 升级到最新python -m pip install --upgrade pip升级完再重新安装 PyQt5大概率就过了。第二种情况你需要安装某些旧版扩展模块或者 PyQt5 的某些附属包没有对应平台的预编译包。这时候的方法是去微软官网下载Visual Studio Build Tools安装时勾选“使用 C 的桌面开发”工作负载这一项体积比较大好几个GB但装完以后几乎所有依赖 C 编译的 Python 包都不再报这个错了。一个实用的排查技巧看到这个报错先看 pip 是在“Building wheel”还是“Downloading”。如果是 Downloading 之后直接报错说明是网络下载的问题如果是 Building wheel 时报错那才是缺编译环境。大多数情况下升级 pip 换源之后这个错就不会再出现了。2.4 装完立刻验证别等 PyCharm 里才后悔安装完成后在命令行里直接验证python -c from PyQt5.QtWidgets import QApplication, QLabel; import sys; app QApplication(sys.argv); label QLabel(Hello PyQt5); label.show(); sys.exit(app.exec_())如果能弹出一个显示 Hello PyQt5 的窗口说明安装成功。强烈建议装完就在这里测一次把“安装问题”和“PyCharm 配置问题”两个变量隔离开后面真要排查时能省一大半时间。如果这个命令弹窗失败最常见的是提示缺失Qt platform pluginWindows 上通常表现为This application failed to start because no Qt platform plugin could be initialized.这个问题的根因90% 是PyQt5 的 DLL 路径没被正确加载。最常用的处理方法是检查环境变量里的PATH是否包含 PyQt5 的Qt\bin目录。新版 PyQt5 一般都是用qt5_applications包来管理这些 DLL 了如果报这个错可以试着重装PyQt5-tools和qt5-applications或者把site-packages\PyQt5\Qt\bin手动加到 PATH 里。3. 把 Qt Designer、PyUIC、Pyrcc 装进 PyCharm外部工具配置全解PyQt5 装好后最核心的一步来了把 Qt 的工具链集成进 PyCharm。这一步做完你就能在 PyCharm 里直接双击打开 .ui 文件设计界面、一键把 .ui 转成 .py 代码、一键编译 .qrc 资源文件整个开发效率完全上一个台阶。先说清楚这三个工具各自的用处不然配置完了也只会机械点按钮工具作用类比Qt Designer可视化拖拽设计界面生成 .ui 文件相当于画图软件PyUIC把 .ui 文件转换成 Python 代码相当于把图纸变成代码Pyrcc把图标、图片等 .qrc 资源编译成 .py相当于把素材打包进程序这三件套配置好了你的开发流程就是Designer 画界面 → PyUIC 转代码 → 在 Python 里写业务逻辑 → 需要图标时用 Pyrcc 打包资源非常清晰。3.1 先找到 designer.exe 在哪不同版本、不同安装方式Qt Designer 的位置不一样。这是配置时最容易卡住的地方。在你找到刚才记录的pip show PyQt5-tools路径后按下面几个位置逐一找新版 PyQt5-tools5.15 以后site-packages\qt5_applications\Qt\bin\designer.exe旧版 PyQt5-toolssite-packages\pyqt5-tools\Qt\bin\designer.exe有时会在site-packages\PyQt5\Qt\bin\designer.exe找不到就用文件管理器搜索designer.exe。注意一定不要双击直接运行它作为验证它在某些环境下双击会闪一下然后消失这是 Qt 插件加载问题不代表文件不存在。直接在 PyCharm 里配置好再调用就行能避免很多不必要的心跳。确认路径后把那个目录记下来比如D:\Python311\Lib\site-packages\qt5_applications\Qt\bin。3.2 配置 Qt Designer打开 PyCharm按下面步骤操作点击菜单File→SettingsWindows或者PyCharm→PreferencesmacOS。找到Tools→External Tools点击右上角的号。弹出对话框里填写Name: Qt Designer Description: Qt 图形界面设计器可任意填写 Program: D:\Python311\Lib\site-packages\qt5_applications\Qt\bin\designer.exe Arguments: 留空 Working directory: $ProjectFileDir$这里的Program要填你实际找到的 designer.exe 的完整路径。Working directory设为项目目录这样 Designer 打开后默认就在当前项目里保存 .ui 文件时方便。3.3 配置 PyUIC把 .ui 变成 .pyPyUIC 不是一个独立的 exe 程序它是 PyQt5 自带的一个模块所以这里配置时要调用 Python 解释器来执行它。继续在同一个 External Tools 界面点新增一项Name: PyUIC Description: 将 .ui 文件转换为 .py 文件 Program: D:\Python311\python.exe Arguments: -m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.py Working directory: $FileDir$注意Program填的是python.exe的路径不是 designer 的路径。Arguments里的$FileName$、$FileNameWithoutExtension$.py、$FileDir$都是 PyCharm 的宏变量表示当前选中文件的名字、没有扩展名的文件名、当前文件所在目录。所以 PyUIC 的作用就是把当前选中的 .ui 文件转换成同名 .py 文件。这个配置的原理不复杂-m PyQt5.uic.pyuic等于告诉 Python“运行 PyUIC 模块”后面跟输入文件名和-o输出文件名和你在命令行手敲是完全一样的效果。3.4 配置 Pyrcc把资源文件编译成 .py和 PyUIC 类似Pyrcc 也是一个模块。新增第三项Name: Pyrcc Description: 编译 .qrc 资源文件为 .py 文件 Program: D:\Python311\python.exe Arguments: -m PyQt5.pyrcc_main $FileName$ -o $FileNameWithoutExtension$_rc.py Working directory: $FileDir$注意这里的输出文件名带了_rc后缀这是 Qt 的一个约定example.qrc编译生成的模块名是example_rc.py在 Python 代码里导入时也是import example_rc。如果你输出名不带_rc代码里导入资源时会找不到模块。这个下划线后缀很多人第一次都会漏掉漏掉的结果就是运行时报 ModuleNotFoundError。3.5 配置完怎么用配置完成后在 PyCharm 的项目文件列表里双击任意一个.ui文件右键 →External Tools→Qt Designer就能打开这个界面设计器。选中.ui文件右键 →External Tools→PyUIC瞬间就会生成一个同名.py文件。选中.qrc文件右键 →External Tools→Pyrcc生成_rc.py文件。这样一个工作流就闭环了。说实话这一套配置才是保姆级教程真正的分水岭。很多教程装完 PyQt5 就结束了结果新手在命令行里跑来跑去敲 uic 命令还经常敲错路径有了 PyCharm 外部工具这层封装写界面这件事就从“命令行苦力”变成了“鼠标点两下”。4. 第一遍走通完整流程从画界面到跑出窗口配置好工具链之后光看不练不行。这一节我们用一个最简单的例子把整个流程跑一遍设计一个带按钮的窗口点击按钮弹出一个提示框。这个流程覆盖了 90% 桌面小工具的开发模式。4.1 用 Designer 画一个最简单的界面在 PyCharm 里右键项目目录 →New→File新建一个demo.ui文件注意不是 Python 文件是普通文件PyCharm 会识别 .ui 扩展名。然后右键demo.ui→External Tools→Qt Designer打开设计器。在 Designer 界面里左侧Widget Box面板里找到Push Button拖到中间的窗口上。右侧Property Editor面板找到text属性把按钮文字改成“点我”。按CtrlS保存关闭 Designer。回到 PyCharm你会看到demo.ui旁边生成了一个demo.py如果没生成右键demo.ui→External Tools→PyUIC手动生成一次。打开demo.py看一眼里面是 PyUIC 自动生成的代码里面有一个Ui_Form类包含了setupUi()方法。记住不要手改这个文件。以后界面要改回 Designer 里改再重新 PyUIC 生成一次就覆盖了。这个习惯一定要养好不然界面改了十几次代码改得一塌糊涂最终一定会乱。4.2 写入口代码跑起来PyUIC 生成的demo.py只是界面的定义还不能直接运行。还需要一个入口文件来组合界面和业务逻辑。新建一个main.py内容如下import sys from PyQt5.QtWidgets import QApplication, QWidget from demo import Ui_Form class MainWindow(QWidget): def __init__(self): super().__init__() self.ui Ui_Form() self.ui.setupUi(self) # 给按钮绑定点击事件 self.ui.pushButton.clicked.connect(self.on_click) def on_click(self): print(按钮被点击了) if __name__ __main__: app QApplication(sys.argv) window MainWindow() window.show() sys.exit(app.exec_())运行main.py正常情况下会弹出一个带按钮的窗口点击按钮后 PyCharm 的控制台会打印出日志。这里解释两个关键点setupUi(self)的作用是把 Designer 里画好的所有控件安装到当前窗口上。传进去的self是窗口对象执行完这个方法后self.ui.pushButton就能直接访问到按钮控件。clicked.connect(self.on_click)是 Qt 的信号槽机制相当于“当按钮被点击时调用 on_click 这个方法”。初学者容易忘import sys或者忘了QApplication这个对象必须创建没有它窗口根本不会弹出来。4.3 信号槽机制新手最需要理解的概念在 PyQt5 里让你画一个静态界面很容易但让界面“动起来”靠的就是信号槽。这个概念本身不复杂——信号就是事件点击、输入、关闭槽就是响应事件的函数。初学者最常见的困惑是为什么我在 Designer 里给按钮连接了信号槽生成代码后却看不到这是因为 PyQt5 有两种信号槽写法在 Designer 里连接适合简单的窗口跳转、关闭窗口等但连接关系存在 .ui 文件里代码中不可见。在代码里用connect连接更灵活可以写成button.clicked.connect(lambda: self.on_click())方便传参。我的建议是界面布局用 Designer信号槽逻辑全部在代码里写。这样代码可读性好也不容易出现 Designer 里的槽方法找不到导致运行时警告的怪问题。4.4 界面改来改去代码怎么同步实际写代码过程中你一定会频繁修改界面。我来分享一个常用的工作模式在 Designer 里修改 .ui 文件。回到 PyCharm右键 .ui →External Tools→PyUIC重新生成 .py 文件。不要动 .py 文件因为它是自动生成的直接覆盖即可。业务逻辑代码写在main.py或单独的逻辑文件里。PyUIC 每次都是全量覆盖生成所以你在 .py 里手动加的代码会被冲掉。解决方案只有一个界面代码和业务代码分离这在项目稍大时受益非常明显。保持住这个习惯你就不会遇到“我改了代码怎么一运行又变回去”的灵异事件。5. 最容易翻车的几个运行时问题软件装好了流程跑通了可以开开心心接需求了。但 PyQt5 在实际使用中还有几个高频问题不少都是“代码没问题、环境出鬼”特地把它们放在一起说能帮你遇到时少掉头发。5.1 OpenGL 导致界面无显示“PyQt5 界面无显示”这个问题在网上被问到过很多次其中相当一部分跟 OpenGL 有关。现象是程序运行时进程存在但窗口一片黑、或者完全空白、又或者直接闪退。通常在控制台能看到类似Could not initialize OpenGL或者 Qt 的警告日志。根因是 PyQt5 某些模块尤其是 QtWebEngine、QOpenGLWidget 以及 3D 相关的组件依赖于 GPU 驱动提供的 OpenGL 支持。Windows 上常见两种情况显卡驱动过老对 OpenGL 2.0 以上支持不完整。远程桌面或虚拟机环境下没有 GPU 直通OpenGL 上下文创建失败。处理方案按优先级排列更新显卡驱动这是最根本的办法。如果是虚拟机或者远程桌面环境可以尝试把 Qt 的渲染后端切到软件渲染。软件渲染的设置方法是在程序开头加环境变量import os os.environ[QT_QUICK_BACKEND] software os.environ[QSG_RHI_BACKEND] software或者直接以命令行方式启动程序时设置set QT_QUICK_BACKENDsoftware set QSG_RHI_BACKENDsoftware python main.py顺带说一句如果你只是用普通的 QWidget、QMainWindow 做桌面工具OpenGL 问题基本不会碰到。遇到这个问题先排查自己代码里是不是用了 QWebEngineView 这类重组件别一上来就怀疑 PyQt5 装坏了。5.2 高分辨率屏幕下界面缩放错乱很多人在笔记本尤其是 2K、4K 高分辨率屏上跑 PyQt5 程序发现界面特别小、字体模糊、文字错位。这是因为 PyQt5 默认不开启高 DPI 自适应。在 PyQt5 5.15 版本之前需要在QApplication创建之前设置import sys from PyQt5.QtCore import Qt from PyQt5.QtWidgets import QApplication # 必须在 QApplication 创建之前设置 QApplication.setAttribute(Qt.AA_EnableHighDpiScaling, True) QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps, True) app QApplication(sys.argv)在 PyQt5 5.15 版本以后这几个属性默认就是开启的但如果你用的是某些旧版代码库或者自定义了缩放环境还是可能出问题。另外也可以尝试设置环境变量set QT_ENABLE_HIGHDPI_SCALING1 set QT_AUTO_SCREEN_SCALE_FACTOR1这两行配置在 Windows 上非常管用直接写到系统环境变量里所有 PyQt5 程序都能受益。5.3 想在程序里显示 HTML两种思路的取舍PyQt5 开发里经常遇到“在窗口里展示一段 HTML 页面”的场景比如显示富文本报表、渲染网页内容。这个需求有两条路很多人一开始就绕进去了方案一QTextBrowser轻量够用from PyQt5.QtWidgets import QTextBrowser browser QTextBrowser() browser.setHtml(h1标题/h1p正文内容/p)适合显示简单的富文本、带样式的文字。优点是轻量、启动快、内存占用低不依赖网络内核。方案二QWebEngineView功能全但重from PyQt5.QtWebEngineWidgets import QWebEngineView view QWebEngineView() view.setHtml(h1标题/h1p正文内容/p)适合显示完整的网页能跑 JavaScript、CSS。缺点是要额外安装PyQtWebEnginepip install PyQtWebEngine并且会引入前面提到的 OpenGL 兼容性问题。我的建议是不需要 JavaScript 的地方一律 QTextBrowser。很多用户一上来就上 QWebEngineView然后被 OpenGL 闪退、打包体积大几十MB这些问题折腾一通最后发现自己只是要显示一段带颜色的文字这就亏大了。5.4 打包成 exe 时的常见坑如果项目最终要给别人用你大概率会用到PyInstaller来打包pip install pyinstaller pyinstaller -w -F main.py有几个坑提前说-w表示不显示控制台窗口但如果你的程序会在控制台打印日志测试阶段先不要加-w不然报错信息全被吞了。打包 Qt 程序体积大是正常的加了 QtWebEngine 会更大。如果对体积敏感用 QTextBrowser 代替 QWebEngineView 是最有效的减负手段。打包后运行提示缺 DLL 时多半是 PyInstaller 版本太旧升级到最新版再试。如果你的代码里用了import example_rc这样的资源模块PyInstaller 有时会漏掉它需要在打包命令里用--hidden-import example_rc显式带上。6. 关于 PyQt5 版本选择和个人使用习惯的建议最后再分享几个实操层面的心得这些是文档里不太会写、但实际开发中确实影响体验的东西。关于 PyQt5 和 PySide2/PySide6 的选择。PyQt5 是 Riverbank Computing 维护的PySide2/PySide6 是 Qt 官方维护的。两者 API 高度相似90% 的代码可以互相复制。如果你只是个人写工具、查资料方便PyQt5 的教程数量确实多得多如果你要考虑商业授权风险PySide 的 LGPL 协议更友好。我的建议是新手阶段用 PyQt5 入门没问题因为社区资料太丰富了。等你有经验了再切 PySide 也不迟切换成本比想象中低很多。关于 Qt Designe 和纯代码布局的选择。很多从 PyQt5 转到纯代码写界面的开发者理由通常是“Designer 生成的代码太乱”或者“控件一多就拖不动”。我个人的体会是窗口类界面用 Designer 效率明显更高自定义控件和动态生成的界面用纯代码更灵活。这俩不是对立关系而是互补关系按需选择就好。新人阶段用 Designer 能更快建立界面开发的直觉别一开始就陷入“手写布局”的自我感动中。关于版本锁定的问题。PyQt5 在 5.15 之后基本停止了大版本更新终端用户使用完全没问题。建议把版本写死在requirements.txt里PyQt55.15.10 PyQt5-tools5.15.9.3 PyQt5-sip12.13.0这样以后在新电脑上部署环境时不会因为某个依赖偷偷升级而出现“我电脑上明明能跑换台电脑就崩了”的情况。配置完这一整套环境之后建议在电脑里存一份配置笔记把 PyCharm 外部工具的具体参数记下来。这一套流程你看着不复杂但三个月后重装系统时要重新回忆一遍那酸爽谁用谁知道。把笔记做好就是把这次的环境搭建成本一次性锁定以后再也不用从零开始踩坑。
