说句实话PyQt5 在 Python 桌面开发里存在感一直很强。你打开 PyCharm敲几行代码再用 Qt Designer 拖一拖控件一个能用的桌面窗体就这么出来了。这也是我最初接触 PyQt5 时的完整路径先装 PyCharm再装 PyQt5然后在 PyCharm 里把设计器、UI 转 py、资源文件编译这三件事串成外部工具。2023 年以后 PyCharm 和 PyQt5 的版本变化都不小很多老教程里的 pyqt5-tools 装法已经失效这篇就按新版本环境重新梳理一遍。这篇内容适合谁刚准备用 Python 写桌面程序、被各种安装教程绕晕的新手以及想把手头 PyQt5 环境重新整理一遍的开发者。整体会分成环境准备、外部工具配置、第一个 Demo、常见问题几个部分文末也会聊一下 PyQt5 和 PySide6 的选型问题。你可以把这篇当作一份可以直接照着操作的清单凡是容易踩的坑我都会特别标出来。1. 配置之前先想清楚这条技术路线1.1 PyQt5 到底给你解决什么问题很多人一上来就问“PyQt5 能不能做界面”实际上它不只是做界面。PyQt5 是 Qt5 框架的 Python 绑定只要你需要窗口、按钮、表格、菜单、多标签页、绘图、网络请求、浏览器内核它都能覆盖。相比 Python 自带的 TkinterPyQt5 控件更丰富样式也更接近现代桌面应用相比用网页做界面PyQt5 不需要额外起服务打包后就是一个原生可执行程序。我用 PyQt5 最多的场景是两类一类是内部工具比如数据清洗软件、日志分析面板、批量文件处理工具另一类是产品原型快速搭出一个能交互的桌面界面给需求方看效果。对于这两类需求PyQt5 的开发效率足够高代码量也不会膨胀到不可维护。不过要注意PyQt5 的核心优势是“成熟的 Qt 生态”但这不代表所有功能装上就能用。比如渲染网页要用 QtWebEngine做图表要用 PyQtGraph播放视频要考虑解码库。你需要的功能越多依赖包也越多这一点在配置环境时就要有心理预期。1.2 用 PyCharm 还是直接用 Qt Creator很多新手会纠结既然 Qt 官方有 Qt Creator为什么还要在 PyCharm 里配 PyQt5我的看法是PyCharm 和 Qt Creator 各管一段。Qt Creator 擅长的部分是可视化编辑界面、管理 .ui 文件、调试 QML而 PyCharm 擅长的是 Python 代码的编辑、补全、重构和断点调试。做 PyQt5 项目大部分时间你在写业务逻辑少部分时间在拖控件所以把 Qt Designer 作为“外部工具”挂在 PyCharm 里比来回切换 IDE 舒服得多。在 PyCharm 里配置外部工具核心思路就是让 PyCharm 能调用三条命令启动 Qt Designer 编辑 .ui 文件、把 .ui 转成 .py、把 .qrc 资源文件转成 .py。配置完成后你只需要在文件上右键就能完成这些操作完全不用打开命令行。1.3 先选 PySide6 还是 PyQt5这是个老生常谈的问题但每次都会有人问。如果你正处于学习阶段我建议直接选 PyQt5理由是网上教程、问答记录、现成代码最多遇到报错容易搜到答案。PySide6 是 Qt 官方维护的 Python 绑定授权协议更宽松API 和 PyQt5 高度接近迁移成本很低但遇到问题时你能查到的资料相对少一些。从实际项目角度看如果只是做内部工具选 PyQt5 没有任何问题如果是商业软件需要仔细看一下 GPL/LGPL 的授权差异PySide6 的 LGPL 在分发时通常更省心。本篇接下来的配置步骤以 PyQt5 为主但它和 PySide6 的配置思路完全一致学会一套另一套也能举一反三。2. 从零搭建Python 环境、PyCharm、PyQt52.1 Python 和 PyCharm 版本怎么选PyQt5 目前稳定支持 Python 3.8 到 3.12建议直接装 Python 3.10 或 3.11兼容性最稳。PyCharm 的话社区版就够用了专业版多出来的是 Web 开发、数据库工具这些功能对于 PyQt5 桌面开发帮助不大没必要为了跑 PyQt5 特意上专业版。如果你只是个人学习和做小工具社区版免费授权完全够用。新版 PyCharm 安装界面上多了很多选项比如是否加入 PATH、是否关联 .py 文件。我的建议是安装时勾选“Add to PATH”这样命令行里直接能用 python 和 pip省去后面的环境变量烦恼。至于默认的启动脚本、主题这些按个人喜好就行。前几年很多人会折腾“PyCharm 激活码”之类的东西这里我给个明确建议别折腾。社区版没有任何功能限制够用于日常 PyQt5 学习如果确实需要专业版功能可以走官方试用或者教育授权网上那些来历不明的“激活工具”反而容易带来风险。2.2 用 Anaconda 还是 venv装完 PyCharm 之后接下来要确定 Python 解释器从哪来。如果你平时做数据分析电脑上已经装了 Anaconda那就直接用 conda 创建虚拟环境在 PyCharm 的 Project Interpreter 里选择已有的 conda 环境即可。如果你没有 Anaconda也可以直接让 PyCharm 帮你在项目里创建 venv这样最省事。我给一个比较落地的建议只是做 PyQt5 小工具用 venv 就够将来还打算用 pandas、numpy、matplotlib 这些科学计算库建议装 Anaconda。因为 conda 管理这些库的依赖更省心不用频繁和编译问题搏斗。如果选择 Anaconda在命令行里先创建一个环境conda create -n pyqt5_env python3.10 -y conda activate pyqt5_env然后在 PyCharm 里打开 File - Settings - Project - Python Interpreter点击 Add Interpreter选择 Conda Environment - Existing environment找到 anaconda3/envs/pyqt5_env/python.exe。这样 PyCharm 就会使用这个干净的隔离环境后续装 PyQt5 也不会影响其他项目。2.3 安装 PyQt5以及 pip 超时怎么解决环境准备好之后安装 PyQt5 本质上就一条命令pip install PyQt5但这几年 PyQt5 的安装坑多了不少。一个是 PyQt5 本身的包变大官方 PyPI 源在国内下载很慢尤其第一次装的时候要拉 Qt 二进制库运气不好会卡很久。另一个是新版会同时安装 PyQt5-Qt5 这个依赖里面是实际的 Qt 运行库如果网络不稳定装到一半就报错。国内用户最直接的解法是换镜像源。我这里推荐清华源命令如下pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simple如果你不想每次输这么长一串可以一劳永逸地配置全局 pip 源。Windows 下在用户目录新建 pip/pip.iniLinux 下是 ~/.pip/pip.conf写入[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple [install] trusted-host pypi.tuna.tsinghua.edu.cn配置好之后再 pip install速度会明显提升。安装完成后可以跑一下验证命令python -c from PyQt5.QtWidgets import QApplication; print(PyQt5 OK)如果正常打印 PyQt5 OK说明环境已经通了如果这一步就报错一般是解释器路径不对或者 Python 版本不匹配回头检查一下 PyCharm 里选的解释器和刚才命令行里用的是不是同一个。2.4 新版 PyQt5 的 designer、pyuic、pyrcc 到底在哪这是配置过程中最容易懵的地方。老教程里通常让你 pip install pyqt5-tools然后去 site-packages 下找 designer.exe。但 pyqt5-tools 这个包停更很久在 Python 3.9 之后容易安装失败所以新版本环境下我不推荐再装它。PyQt5 官方包实际上自带 Qt 的相关二进制文件。装完 PyQt5 后在 Python 环境的 site-packages 目录下你会看到 PyQt5 文件夹里面有一个 Qt 子目录Qt 目录下有 binbin 下就有 designer.exe、linguist.exe、assistant.exe 这些工具。如果你用 venv路径大致是venv/Lib/site-packages/PyQt5/Qt/bin/designer.exe如果是 conda 环境路径是envs/pyqt5_env/Lib/site-packages/PyQt5/Qt/bin/designer.exe而 pyuic 和 pyrcc 这两个工具在 PyQt5 中不建议直接调用 exe而是用 Python 模块方式执行对应命令是python -m PyQt5.uic.pyuic xx.ui -o xx.py python -m PyQt5.pyrcc_main xx.qrc -o xx_rc.py用模块方式的好处是不用关心 pyuic.exe 的路径只要当前 Python 环境里装了 PyQt5命令就能跑。这一点对后续配置 PyCharm 外部工具特别关键因为 PyCharm 可以动态获取当前解释器路径这样你切换项目环境后配置也不会失效。3. 把 Qt Designer、PyUIC、PyRcc 配置成 PyCharm 外部工具3.1 先理解外部工具的配置原理PyCharm 的 External Tools 功能本质上就是在菜单栏里帮你执行一条预设命令。你平时在命令行里手动做的事它帮你封装成一个按钮。配置的核心就是四个字段名称、Program、Arguments、Working directory。Program 是程序路径Arguments 是参数Working directory 是执行命令时的工作目录。配置好了之后PyCharm 会在你右键文件时显示对应的工具菜单自动把当前文件名、路径填充到宏变量里。这套机制在老版本和新版本里一直存在只是设置入口的位置稍有变化。新版 PyCharm 中打开 File - Settings - Tools - External Tools点击左上角的加号就可以新增工具。界面是全英文的字段名不过内容很少照着填就行。3.2 添加 Qt DesignerQt Designer 的作用是可视化编辑 .ui 界面文件。在 External Tools 窗口中点击加号填写如下内容NameQt DesignerProgram选择你当前 Python 环境下的 designer.exe也就是上面提到的 site-packages/PyQt5/Qt/bin/designer.exeArguments留空Working directory$ProjectFileDir$这里有一个更稳妥的写法。为了防止以后换环境时路径失效你可以把 Program 填成$PyInterpreterDirectory$/../Lib/site-packages/PyQt5/Qt/bin/designer.exe$PyInterpreterDirectory$ 是 PyCharm 的宏表示当前解释器所在的目录。这个写法在 Windows 的 venv 和 conda 环境下都成立。如果你装了 PyQt5 之后找不到 designer.exe先在 Python 里执行一下import PyQt5 print(PyQt5.__file__)拿到 PyQt5 包的路径再往上找到 Qt/bin/designer.exe基本就在那个位置。3.3 添加 PyUICPyUIC 负责把 .ui 文件转成 Python 代码。这里的参数比较讲究填错就会生成到奇怪的位置。在 External Tools 中新增填写NamePyUICProgram$PyInterpreterDirectory$/python.exeArguments-m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.pyWorking directory$FileDir$我来逐个解释为什么这么写。Program 用了 python.exe这样不管 PyQt5 装在哪只要是当前解释器环境就能通过 python -m 找到 pyuic 模块。Arguments 里 $FileName$ 是当前右键选中的文件名PyUIC 会把这个文件作为输入$FileNameWithoutExtension$.py 表示把主文件名取出来加上 .py 后缀生成在同一个目录下。比如你右键 demo.ui执行这条命令就会生成 demo.py。Working directory 填 $FileDir$ 表示输出文件默认在当前文件所在目录避免生成到项目根目录或者临时目录里。3.4 添加 PyRccPyRcc 负责把 .qrc 资源文件转换成 .py 文件。资源文件里通常放着图片、图标、样式表、字体等Qt Designer 中引用这些资源时最终编译出来的 .ui 代码会默认 import 一个xxx_rc模块所以 PyRcc 生成的命名要特别注意。新增工具时填写NamePyRccProgram$PyInterpreterDirectory$/python.exeArguments-m PyQt5.pyrcc_main $FileName$ -o $FileNameWithoutExtension$_rc.pyWorking directory$FileDir$如果你右键的是 resources.qrc运行后会生成 resources_rc.py。Qt Designer 生成的 .ui 文件里如果加载了 resources.qrc转成 py 后会自动出现import resources_rc因为命名规范一致所以这一步不要省也不要自己乱改名。3.5 三个工具的配置参数对照表把三个工具放在一起对比配置起来会更清楚工具名ProgramArgumentsWorking directoryQt Designer$PyInterpreterDirectory$/../Lib/site-packages/PyQt5/Qt/bin/designer.exe留空$ProjectFileDir$PyUIC$PyInterpreterDirectory$/python.exe-m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.py$FileDir$PyRcc$PyInterpreterDirectory$/python.exe-m PyQt5.pyrcc_main $FileName$ -o $FileNameWithoutExtension$_rc.py$FileDir$如果你的 designer.exe 不在默认路径下直接把 Program 换成手动浏览到的绝对路径也可以。少数情况下 $PyInterpreterDirectory$ 宏取到的目录不是站点包所在位置建议第一次配置成功后自己验证一下。3.6 配置完成后怎么用配置好三个工具后使用流程就很顺了。先右键项目中的任意位置选择 External Tools - Qt Designer这时 Qt Designer 会打开拖好控件保存为 demo.ui。然后右键 demo.ui选择 External Tools - PyUICPyCharm 会在同目录下生成 demo.py。如果界面里用了资源再对 resources.qrc 执行 PyRcc生成 resources_rc.py。整个过程不需要手动输命令也不需要在多个窗口之间来回切换。这也是我推荐在 PyCharm 里配置外部工具的原因流程一旦固化下来效率提升非常明显。尤其当你频繁改界面时重新生成 UI 文件只是一次右键操作而不是翻终端敲命令找目录。4. 第一个 Demo把界面文件和逻辑拆开跑起来4.1 用 Qt Designer 画一个简单窗口配置好外部工具之后我们先做一个最小可用例子。在 PyCharm 中新建一个项目目录比如 pyqt5_demo然后右键项目根目录选择 External Tools - Qt Designer。Qt Designer 打开后在左侧模板里选择 Main Window点击 Create 创建主窗口。然后从左侧控件栏拖一个 QLabel 和一个 QPushButton 到窗口上将按钮的 text 改为“点我”保存为 demo.ui。保存时注意文件名用英文不要带空格否则后续命令处理容易出问题。Qt Designer 界面上会有“编辑信号槽”模式但这里我们先不连信号槽业务逻辑放到生成的 Python 代码里处理。这是 PyQt5 推荐的做法.ui 只描述界面结构和布局不改动生成代码业务逻辑写在另一个模块里。4.2 用 PyUIC 转成 demo.py在 PyCharm 中右键 demo.ui选择 External Tools - PyUIC会生成一个 demo.py。切到 demo.py 查看内容核心结构是一个 Ui_MainWindow 类里面有两个方法setupUi 负责构建所有控件并设置布局retranslateUi 负责处理翻译相关文本。这个文件是自动生成的不要手动改。如果你之后在 Qt Designer 里改了界面回到 PyCharm 重新执行一次 PyUIC 即可旧的 demo.py 会被覆盖。因为生成代码和手写逻辑分离所以覆盖也不会影响你写好的业务代码。4.3 写业务主入口 main.py现在新建一个 main.py写入以下代码import sys from PyQt5.QtWidgets import QApplication, QMainWindow from demo import Ui_MainWindow class MainWindow(QMainWindow, Ui_MainWindow): def __init__(self): super().__init__() self.setupUi(self) self.pushButton.clicked.connect(self.on_button_clicked) def on_button_clicked(self): self.label.setText(你点击了按钮) if __name__ __main__: app QApplication(sys.argv) window MainWindow() window.show() sys.exit(app.exec_())这里的关键是 MainWindow 同时继承了 QMainWindow 和 Ui_MainWindow然后调用 setupUi(self) 完成界面初始化。这样你在 Qt Designer 里起的控件名比如 pushButton、label可以直接通过 self.pushButton、self.label 访问。运行 main.py如果一切正常会弹出一个窗口点击按钮后标签文本会变化。到这里PyQt5 的整个开发闭环已经跑通了。4.4 界面和逻辑分离能避免什么坑很多新手喜欢在 demo.py 里直接塞业务逻辑比如点击事件、数据处理代码。短期内看是省事了但只要你回 Qt Designer 调整一次界面再执行 PyUIC这些手写代码就会全部被覆盖辛辛苦苦写的东西就没了。正确的做法是像上面这样demo.py 只负责界面构建业务逻辑全写在 main.py 里。这个模式对应到 Qt 的经典 MVC 思路界面是视图业务逻辑是控制器。哪怕项目变大也只是多几个模块的事不会因为界面调整产生大量连带修改。我在实际工作中见过不少因为不分离导致的重写事故改一次界面对应着改一遍逻辑文件。所以这个习惯最好一开始就养好而不是等项目做大了再回头重构。5. 常见问题与排查实录5.1 OpenGL 导致 PyQt5 界面无显示这些年被问得最多的一个问题就是程序运行后没有窗口或者窗口一闪而过黑屏。控制台里如果出现 QOpenGLContext 相关的提示大概率是 OpenGL 环境的问题。Qt5 在 Windows 上默认走 OpenGL 做渲染但如果你的显卡驱动太老、远程桌面连接、虚拟机环境或者某些集显设备OpenGL 支持不全就会导致界面无法正常显示。解决方案是在创建 QApplication 之前启用软件 OpenGLimport sys from PyQt5.QtCore import Qt from PyQt5.QtWidgets import QApplication QApplication.setAttribute(Qt.AA_UseSoftwareOpenGL) app QApplication(sys.argv)也可以直接设置环境变量QT_OPENGLsoftware两者任选其一。如果设置了之后还是黑屏再检查是不是用了 QOpenGLWidget 或者 QML 相关内容这类组件对渲染上下文要求更高软件渲染也不一定完全规避问题。5.2 pip 安装 PyQt5 慢或者卡住前文提到了换清华源这基本是解决安装慢的最有效手段。但如果你已经配置了全局镜像安装时还是卡在 Downloading 阶段不动可能是 PyQt5-Qt5 这个二进制包比较大网络波动导致下载中断。此时先把 pip 升级一下再重试python -m pip install --upgrade pip pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simple另外提醒一句不要在 PyCharm 的终端里反复多次强行安装出现超时可以先把 pip 缓存清一下pip cache purge然后再安装避免旧的缓存文件影响。5.3 designer.exe 双击没有反应如果你的 designer.exe 双击之后没有窗口弹出先别急着重装。可能是这个 exe 在后台已经启动只是没显示到当前桌面去任务管理器里看看有没有 Qt Designer 进程有就结束进程再试。也可能是你装的是 pyqt5-tools 提供的旧版 designer和当前 Python 版本不兼容换成 PyQt5 自带 Qt/bin/designer.exe 就没问题了。如果双击后闪退可以在命令行里直接运行 designer.exe 看报错信息。多数情况下问题集中在缺少 VC 运行库或者显卡驱动异常上装上对应运行库或者按前面 OpenGL 的方式处理一下基本能解决。5.4 生成的 UI 模块提示 ModuleNotFoundError运行 main.py 时报 ModuleNotFoundError: No module named demo通常是当前目录没有加入 Python 搜索路径。在 PyCharm 中右键项目根目录选择 Mark Directory as - Sources Root可以解决大部分这类问题。如果还不行检查一下 demo.py 和 main.py 是否在同一个目录下。还有一个容易被忽略的是文件名问题。如果你保存的是“我的界面.ui”PyUIC 生成的模块名会被转成 ASCII 形式或者直接报错所以从第一步起就坚持用英文小写命名能避免后续很多奇怪问题。5.5 界面在高分辨率屏幕上模糊Windows 下高分辨率显示器默认对旧程序做缩放处理PyQt5 界面如果没启用高 DPI 支持会显得很模糊。解决办法是在创建 QApplication 之前开启高 DPI 缩放from PyQt5.QtCore import Qt from PyQt5.QtWidgets import QApplication QApplication.setAttribute(Qt.AA_EnableHighDpiScaling) QApplication.setAttribute(Qt.AA_UseHighDpiPixmaps) app QApplication(sys.argv)注意这两行必须放在 QApplication 创建之前否则不生效。Qt 5.15 之后对高分辨率支持已经比较成熟大部分情况加了这两行就能解决问题。如果还没缓解看一下系统显示缩放比例是否设置为 100% 以上配合软件设置一起调整。5.6 PyQt5 显示 HTML 怎么做如果你只是显示一段富文本用 QTextEdit 或者 QTextBrowser 就可以直接调用 setHtml 方法。但如果你要显示的是一个完整网页比如带 JavaScript 的页面就得用 QWebEngineView它是基于 Chromium 的浏览器内核。装包命令pip install PyQtWebEngine然后在代码里引入from PyQt5.QtWebEngineWidgets import QWebEngineView有网友会问 WebView2 和 QWebEngineView 的区别这里简单说明一下WebView2 是微软基于 Edge 内核的嵌入式浏览器组件PyQt5 本身并没有原生封装 WebView2如果你一定要用 WebView2需要额外通过 pythonnet 或者官方接口去调用比较折腾。对大多数 PyQt5 应用来说QWebEngineView 已经够用。5.7 安装时出现 pyqt5-qt5 registry 相关报错有段时间 pip 安装 PyQt5 时会看到类似 distribution pyqt5-qt55.15.19 registryhttps://pypi.tuna 这样的提示。这是镜像源元数据解析问题不影响最终结果但如果你用 pip list 检查可能会发现 PyQt5-Qt5 的版本显示异常。处理办法是先把已装的卸载干净重新用官方源或者清华源再装一次pip uninstall PyQt5 PyQt5-Qt5 -y pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simple大多数情况下重装一遍就正常了。如果重装后还有类似提示多半是本地 pip 版本过旧升级 pip 即可。6. 版本和生态2023 年之后怎么选型6.1 PyQt5/PySide6/PyQt6 横向对比很多人在配置环境时会纠结一个问题现在明明有 PyQt6 和 PySide6为什么还要学 PyQt5这个问题要看你处于什么阶段。我给一个对比表项目PyQt5PySide6PyQt6授权协议GPL/商业授权LGPL/商业授权GPL/商业授权当前维护状态稳定维护新功能有限Qt 官方维护持续更新Riverbank 维护更新中Python 版本支持3.8-3.123.93.9教程和资料量最多中等中等适合场景学习、成熟项目、资料优先商业项目、长期维护需要新特性的新项目我的建议是如果你是为入门学习选 PyQt5 没问题踩坑时能搜到几百个结果如果你是商业项目优先考虑 PySide6授权更友好如果追求新特性且不担心资料少可以上 PyQt6。这三者 API 差别比较小从 PyQt5 切换到 PySide6基本就是把 import 从 PyQt5 改成 PySide6再改几个枚举名而已。6.2 新版 PyCharm 和 AI 插件现在新版本 PyCharm 里已经能接不少 AI 辅助插件比如 Codex、Claude Code 这类可以辅助你生成界面代码或者补全逻辑。但这类插件不会替代外部工具的配置它们更多是帮你写代码不会帮你把 .ui 转成 .py。如果你在较新版本的 PyCharm 里找不到 External Tools 入口不要慌。设置界面这部分被改过几次打开 Settings 后直接搜索 External Tools一般都能跳转到对应页面。我的习惯是配置完之后再给每个工具设置一个快捷键这样连右键都省了效率更高。6.3 关于 PyCharm 激活和版本更新的提醒经常有人问“PyCharm 哪个版本最好用”。我的观点是只要不是太老的版本选最新的稳定版就行。社区版是免费开源的做 PyQt5 开发完全够用没必要到处找激活码。如果你看到某个视频或者文章说“必须用专业版”那基本是推广话术不用理会。安装新版 PyCharm 后之前配置的外部工具一般不会丢因为配置信息存在用户目录下。换电脑或者重装系统后可以导出一份配置备份或者按这篇文章重新配置一遍几分钟就搞定。配置 PyQt5 工具链这件事最核心的不是记参数而是理解外部工具的本质命令加参数。我在实际使用中有一个习惯每个新项目建好后先用 5 分钟把三个外部工具确认一遍看看 Program 路径是否指向当前环境的 python.exe 和 designer.exe。这样等项目写大了不会因为环境切换突然找不到工具链。这篇教程已经覆盖了从环境准备、外部工具配置到第一个 Demo 的完整流程也把常见问题都放在了一处。最后再分享一个小技巧如果你以后经常写 PyQt5 项目可以把这个配置流程整理成一份团队文档新同事入职时照着配一次基本 10 分钟内就能开始写界面不用再经历一遍我当初踩过的那些坑。