1. 安装前先把 Python 环境这个地基打牢1.1 先搞清楚你电脑上到底有没有 Python很多小白一上来就直接复制 pip install PyQt6 的命令回车之后看到一堆红色报错人就傻了。其实这个问题的根源往往不是 PyQt6 本身而是你自己电脑上压根就没装 Python或者装了但没配置好环境变量。所以第一步我建议你先打开命令行。在 Windows 上你直接按键盘上的 Win R输入 cmd 然后回车会弹出一个黑色的窗口。这个窗口就是你跟电脑对话的地方。在窗口里输入python --version或者python -V然后按回车。如果屏幕上显示类似Python 3.12.2这样的信息说明你的电脑已经装了 Python。如果显示不是内部或外部命令或者python 不是内部或外部命令也不是可运行的程序或批处理文件那说明系统找不到 Python你得先装一个。这里有个很容易混淆的地方有时候你输入python没反应但输入py却有反应。这是 Windows 自带的一个 Python 启动器Python Launcher在有些情况下它能调用系统里已装的 Python。如果你看到的是这种状态也可以继续但为了后续操作简单我更建议你把 Python 的环境变量彻底配好让python和pip两条命令都畅通无阻。1.2 没有 Python 的话装哪个版本最合适Python 的版本非常多PyQt6 对 Python 版本有明确的要求。根据我个人的实操经验Python 3.9 到 3.12 之间的版本都兼容 PyQt6再老的比如 3.6、3.7 可能就装不上最新版 PyQt6 了因为官方在新版本里逐步放弃了对老版本 Python 的支持。我给你的建议是装 Python 3.10 或 Python 3.11。这两个版本非常成熟兼容性极好第三方的各种库基本都支持而且网上问问题的教程也大多基于这些版本遇到问题容易找到答案。下载地址就是 Python 官方站点https://www.python.org/downloads/。打开页面后你会看到一个黄色的大按钮写着Download Python 3.xx.x点它就会下载一个.exe安装包。下载完成后双击运行安装包。这一步非常关键你一定要注意勾选窗口最底部的Add python.exe to PATH选项这个选项决定了你的系统能不能用python命令。很多小白就是这一步没勾选后面才出现命令找不到的问题。至于安装路径默认装到C:\Users\你的用户名\AppData\Local\Programs\Python就可以不用改。2. 核心安装步骤用 pip 把 PyQt6 拉下来2.1 先升级 pip别让老版本拖后腿Python 装好之后接下来就轮到 pip 登场了。pip 是 Python 自带的包管理工具它的作用就像一个应用商店你告诉它你需要什么库它就自动帮你下载并安装到系统里。在装 PyQt6 之前我强烈建议你先把自己的 pip 升级到最新版本。老版本的 pip 在解析依赖关系时经常出错尤其是一些稍微复杂点的库安装起来问题特别多。这一步非常简单在刚才的命令行窗口里输入python -m pip install --upgrade pip看到下载进度条走完然后显示Successfully installed pip-xx.x.x就说明升级成功了。这里说一下为什么用python -m pip而不是直接pip。在 Windows 上直接敲pip通常也能运行但如果你电脑上装了多个 Python 版本直接敲pip有可能会调用了错误版本的 pip导致库装到了别的 Python 环境里。而python -m pip明确指定了用当前这个 python 对应的 pip 去操作这样就绝对不会有版本错乱的问题。这是个非常好的习惯。2.2 正式安装 PyQt6接下来就是最核心的一步安装 PyQt6。命令行里输入python -m pip install PyQt6回车之后你会看到 pip 开始下载 PyQt6 以及它的一堆依赖包比如 PyQt6-sip、PyQt6-Qt6 这些。这一步需要等待一会儿PyQt6 完整安装包大概有几十 MB具体时间取决于你的网速。稍微解释一下为什么会有这么多附带的包。PyQt6 不是一个单体程序它由三大部分组成核心模块就是你 import 时候用的 PyQt6、Qt6 的各类动态链接库Qt6Core、Qt6Widgets 这些 DLL 文件、以及一个底层接口层 PyQt6-sip它负责把 C 写的 Qt 库转成 Python 能调用的接口。这些组件缺一不可所以 pip 才会把它们一并装齐。你不需要关心它们各自是什么只需要知道这些都是正常安装流程的一部分别看到装了一堆东西就觉得哪里出错了。如果你看到最后一行输出Successfully installed PyQt6-6.7.0 PyQt6-Qt6-6.7.0 PyQt6-sip-13.6.0恭喜你安装成功了。版本号可能跟这个不完全一样这是正常的因为官方会持续发布新版本只要显示出这三个包名就说明核心的 PyQt6 已经就位了。2.3 加载太慢切换国内镜像源有个非常常见的情况pip 安装 PyQt6 的时候进度条半天不动或者直接报超时错误。这个问题的根因是你连的 pip 官方源在国外网络访问速度慢得像乌龟爬。解决办法很简单改用国内镜像源。国内有多个 Python 包镜像站点比如清华、阿里云、豆瓣这些。我给小白推荐最稳妥的清华源。直接用下面的命令就能从清华源安装 PyQt6顺便把 pip 的默认源永久改成清华源python -m pip install PyQt6 -i https://pypi.tuna.tsinghua.edu.cn/simple如果想让以后的每次安装都自动走清华源可以执行一次python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple执行之后以后再装任何 Python 包都会默认这个源。个人非常推荐做这一步因为国内开发环境访问官方源实在是太不稳定了改完之后下载速度能从几十 KB/s 飙升到几 MB/s体感完全不同。注意镜像源可能会有访问波动如果遇到清华源报 403 或者超时可以临时换用阿里镜像https://mirrors.aliyun.com/pypi/simple/命令换成-i https://mirrors.aliyun.com/pypi/simple就行。3. 安装完成后先别急验证一下环境3.1 用一段最小代码测试 PyQt6 能否导入装完之后很多人喜欢直接去跑复杂的程序结果各种报错根本不知道问题出在 PyQt6 身上还是代码本身。我先给你一个最小验证方案。在命令行窗口里输入python回车你会看到光标变成了的样子这表示进入了 Python 的交互模式。然后输入from PyQt6.QtWidgets import QApplication, QWidget print(PyQt6 导入成功)如果屏幕上能看到PyQt6 导入成功这句话那 PyQt6 的安装就已经确认没问题了。如果报了ModuleNotFoundError: No module named PyQt6说明库没装进当前环境或者你打开命令行的路径不对。验证完不用急着退出按Ctrl Z再按回车就退出了 Python 交互模式回到命令行。3.2 顺手把虚拟环境这个好习惯建立起来说到这个小节我想多提一句虚拟环境的概念。很多小白图省事直接把自己电脑里那个全局的 Python 当所有项目的运行环境这个做法短期看着没问题等装了几十个库之后就开始头疼了。你想想这个场景项目 A 需要 PyQt6 6.6项目 B 因为某些依赖冲突只要 6.2如果你全装在全局环境里那 A、B 两个项目必然有一个跑不起来。虚拟环境就是给每个项目一个独立的包仓库互不干扰。创建虚拟环境其实很简单在命令行里切到你的项目目录然后执行python -m venv venv这会在当前目录下创建一个名为venv的文件夹里面就装着独立的一套 Python。然后激活它venv\Scripts\activate看到命令行前面出现(venv)字样就说明虚拟环境已经激活了。再执行之前装 PyQt6 的命令库就会装进这个虚拟环境里不会污染系统全局环境。提示只要你在虚拟环境里以后关闭项目重开终端后要装包第一步永远是先venv\Scripts\activate进入环境再执行 pip 命令。好多人隔天回来继续开发说为什么装过的包不见了其实就是忘了激活虚拟环境。4. 让 PyQt6 真正跑起来编写你的第一个窗口4.1 一段能直接运行的窗口代码验证好导入没问题之后我带你写一个真正的图形窗口程序。你不用完全理解每一行的含义先复制运行看到窗口弹出来这个成就感就是最好的动力。新建一个文本文件把下面这段代码粘贴进去保存为first_window.py然后命令行执行python first_window.pyimport sys from PyQt6.QtWidgets import QApplication, QWidget # 每个 PyQt6 程序都必须有一个 QApplication 实例它管理整个应用的生命周期 app QApplication(sys.argv) # 创建一个顶级窗口 window QWidget() window.setWindowTitle(我的第一个 PyQt6 窗口) window.resize(640, 480) # 显示窗口 window.show() # 进入事件循环等待用户操作 sys.exit(app.exec())如果一切正常你的屏幕上应该弹出一个标题为我的第一个 PyQt6 窗口的空白窗口宽 640 像素、高 480 像素。你可以拖动它、最小化它、最大化它甚至关闭它。虽然不是多惊艳的东西但这一瞬间你实际上已经构建了一个完整的桌面应用骨架。4.2 逐行拆解代码小白也能读懂我猜你现在对这段代码还是一头雾水没关系我逐行给你讲讲这比背代码有用得多。首先QApplication是整个程序的总管家。PyQt6 的每个应用都必须先创建一个 QApplication 对象而且每个进程只能创建一个。它负责处理窗口系统的底层初始化比如消息循环、全局事件分发。你记住一句话就行没有它你啥窗口都弹不出来。参数sys.argv是命令行参数列表。简单说就是把你在命令行输入的参数传进去目的是让 PyQt6 能识别程序名或某些启动参数。即使你用不到参数也得传一个空列表进去这是 API 的固定要求。接着QWidget()创建了一个空白窗口。在 Qt 的世界里QWidget是最基本的 UI 容器它没有菜单栏、工具栏、状态栏就是一块纯粹的空画布。之后你往里加按钮、标签、输入框往哪加就加在 QWidget 身上。setWindowTitle和resize就不用多说了一个是改标题一个是改默认尺寸。真正的难点在于最后两行的配合window.show()负责把窗口显示出来而app.exec()则是让程序进入事件循环状态。所谓事件循环你可以把它理解成一个永不停歇的值班前台。窗口显示出来之后用户可能会点按钮、敲键盘、拖窗口这些操作都会产生事件事件循环就是不停接听这些事件并把它们转发给对应的处理代码。如果去掉app.exec()窗口会一闪而过直接结束程序就退出了。而sys.exit(app.exec())的意思是等应用的事件循环结束后把退出码传给操作系统让程序干净利落地退出。这里sys.exit不是强制退出而是优雅退出。4.3 加两个按钮感受一下交互是怎么回事光显示一个空白窗口还不够体验太差了。我建议你再往里面加点料比如一个按钮点击之后改变窗口里标签的文字。修改代码如下import sys from PyQt6.QtWidgets import QApplication, QWidget, QPushButton, QLabel, QVBoxLayout class MyWindow(QWidget): def __init__(self): super().__init__() self.setWindowTitle(PyQt6 交互示例) self.resize(400, 300) # 创建一个垂直布局 layout QVBoxLayout(self) # 一个标签用于显示文字 self.label QLabel(你还没有点击按钮) layout.addWidget(self.label) # 一个按钮 self.button QPushButton(点我试试) layout.addWidget(self.button) # 把按钮的点击事件连接到改文字的方法 self.button.clicked.connect(self.on_click) def on_click(self): self.label.setText(按钮被点击了) app QApplication(sys.argv) window MyWindow() window.show() sys.exit(app.exec())这段代码里你第一次接触到了信号与槽。clicked是按钮发出的信号on_click是处理信号的槽函数connect把两者连接起来。用大白话说当用户点击按钮时程序会自动执行on_click方法。理解信号与槽是 PyQt6 的核心几乎所有的交互逻辑都建立在它上面。你不用一步到位掌握全部先跑通这个例子知道控件能发出信号方法能接收信号这个思路后面学起来会顺畅很多。5. 开发工具套装Qt Designer 和 PyInstaller5.1 可视化设计界面别再用代码硬绘布局了等你写了一点代码、体验过布局之后一定会产生一个感觉用代码写界面太慢、太枯燥了改一个字都要重新运行程序看效果。这时候你需要一个神器Qt Designer。Qt Designer 是 Qt 官方提供的可视化界面设计工具你用它拖拽按钮、文本框、表格所见即所得生成一个.ui文件然后再用工具把这个文件转换成 Python 代码。它极大地降低了界面开发的门槛。PyQt6 安装包默认就会包含这个工具但它的启动路径可能不太显眼。你可以用命令行启动python -m PyQt6.uic.pyuic --help如果你安装了完整版本的 PyQt6通常在 Python 安装目录下的Lib\site-packages\PyQt6\Qt6\bin文件夹里能找到designer.exe。为了使用方便我建议你把这个路径加到环境变量里或者在桌面建一个快捷方式指向它。但说实话最直接的方式还是安装 PyQt6 工具包python -m pip install pyqt6-tools该包会提供一个更便捷的 designer 启动命令pyqt6-tools designer小知识.ui文件本质上是 XML 格式的界面描述文件。你在 Designer 里画完界面保存为my_design.ui然后执行python -m PyQt6.uic.pyuic my_design.ui -o my_design.py就能自动生成一个 Python 类里面已经有你画的控件和属性。这样搭界面速度快很多也能减少手写代码时的小错误。但是注意自动生成的代码不要手动去改因为每次重新生成都会覆盖你的修改。正确做法是新建一个 Python 文件导入生成的类在它基础上再扩展逻辑。5.2 把你的小程序打包成 .exe 分享给别人程序写好之后你总不能每次都让朋友先装 Python 再运行你的.py文件吧。这时候就需要把程序打包成 Windows 能直接双击运行的.exe文件。思路非常成熟主要用 PyInstaller。安装python -m pip install pyinstaller打包python -m PyInstaller --onefile --windowed first_window.py参数解释来一波--onefile把所有东西都打成一个单独的.exe方便分发。代价是启动速度会稍微慢一点因为运行时需要临时解压所有依赖。--windowed启动程序时隐藏黑色命令行窗口。桌面应用一般都要加这个参数否则打开程序会先闪一个黑框非常不专业。打包完成后在dist文件夹下就能找到first_window.exe。把这个文件拷到任何一台 Windows 电脑上只要那台电脑有 Windows 系统基本都能直接运行。当然目标机器最好也是 64 位系统因为默认打出来的 exe 是 64 位的。打包这块有个经验要分享如果程序里用到了图片、配置文件等外部资源默认情况下 PyInstaller 不会自动帮你打包进去需要在.spec文件里手动添加或者用--add-data参数指定。这事儿很容易被遗忘我早期踩过不少坑打包出来的 exe 发给朋友运行时报找不到图片那叫一个尴尬。6. 小白最容易踩的坑我帮你全填平6.1 常见报错信息速查表以下这几种报错90% 的小白都会遇到我整理成了对照表你直接照着排查。报错内容原因分析解决方案python 不是内部或外部命令Python 未安装或未加入 PATH重新运行 Python 安装包勾选Add python.exe to PATHModuleNotFoundError: No module named PyQt6PyQt6 未安装或装到了别的 Python 环境执行python -m pip install PyQt6确保在正确的虚拟环境内Unable to find the Qt platform plugin windowsQt 找不到平台插件通常发生在打包或路径异常时检查 PyQt6 安装目录是否完整打包请用 PyInstaller 的--windowed模式不要手动删 Qt 目录里的文件AttributeError: module PyQt6 has no attribute QtWidgets导入方式写错了确保是from PyQt6.QtWidgets import而不是import PyQt6.QtWidgets后用PyQt6.QtWidgets.QApplication后者其实也可以但要完整引包格式DLL load failedPyQt6 依赖的 DLL 文件被查杀软件拦截或安装不完整关闭杀毒软件/安全卫士后重装 PyQt6确保系统为 64 位pip install 报 timed out连接官方源太慢加-i 镜像地址参数或永久配置清华源6.2 装库时提示已安装但代码里就是导入不了这是另一个高频问题。很多时候你执行pip install PyQt6终端回复Requirement already satisfied你以为装好了结果一运行程序还是报ModuleNotFoundError。这个诡异的情形绝大多数归结于你出现了多个 Python 环境。可能是之前装了 Anaconda后来又装了官方 Python可能是被 IDE比如 PyCharm自动创建的虚拟环境干扰也可能是你自己手动建过 venv 然后忘了。总之pip装库的目标环境和你运行代码所使用 Python 的环境不是同一个。解决办法非常直接python -m pip install PyQt6这串命令里的python到底是什么你可以先执行where python看看路径。如果输出了多个路径说明系统里有多个 Python 在抢python这个命令的指向。更稳妥的方案是在你要运行代码的 IDE如 PyCharm里打开 Settings → Project → Python Interpreter看看当前解释器路径然后直接在下方列表里点击号搜索 PyQt6 安装。这样库会装到当前项目绑定的解释器里绝对不会装错。记住一句话pip 装到哪个 Python 里代码就必须用哪个 Python 跑。6.3 卸载重装时要彻底清理有时候遇到版本问题实在解决不了你会考虑卸载重装。卸载本身很简单python -m pip uninstall PyQt6 PyQt6-Qt6 PyQt6-sip注意这三个包要一并卸掉只卸 PyQt6 而留下 Qt6 的 DLL 文件重装时可能因为版本不匹配导致报错。卸载结束后再去 Python 的site-packages目录里检查有没有残留的 PyQt6 相关文件夹如果有就手动删除。Windows 上不会完全自动清干净手动删一下更放心。重装时建议明确指定版本号避免装到最新版以后出现不兼容python -m pip install PyQt66.6.1 PyQt6-Qt66.6.1 PyQt6-sip13.6.0安装指定版本还有个额外的好处如果你想参考网上的代码而网上的代码是基于 6.5 版本写的你装最新 6.9 可能会有 API 变动不兼容的问题。指定版本就能严格对齐教程环境减少踩坑。6.4 控件是英文/中文显示异常设置字体我曾经遇到过一个很诡异的问题程序跑起来界面按钮上的中文显示成了方框。排查了半天才发现是 Windows 系统里默认的 UI 字体渲染在 Qt 中有兼容问题。这种情况虽然不常见但一旦遇到非常劝退新人。解决方案一个是设定全局字体from PyQt6.QtGui import QFont app.setFont(QFont(Microsoft YaHei, 9))Microsoft YaHei 是微软雅黑Windows 系统自带对中文渲染非常友好。另一种更彻底的方法是设置环境变量set QT_QPA_PLATFORMwindows:fontenginefreetype这样强制 Qt 使用 FreeType 字体引擎渲染文字很多中文乱码问题都能迎刃而解。不过这种方法通常只有在程序发布到别的电脑上出现字体问题时才需要开发机上一般用第一种方式就够了。跑完整个流程你的电脑现在应该已经具备了一个完整的 PyQt6 开发环境Python 解释器、PyQt6 库、可视化设计工具、打包工具甚至踩坑经验也备齐了。我个人在实际安装和后续开发中最大的体会是PyQt6 的安装本身其实并不算难真正卡住人的反而是那些看起来无关的小事——环境变量没配好、多个 Python 版本互相干扰、pip 源太慢、装完不知道先验证一下。只要顺着这篇文章的顺序一步步来每一步都确认一下结果大概率一次就能跑通。而且在开发过程中我建议你从一开始就养成交替使用交互式验证和最小化样例的习惯遇到问题能快速圈定范围千万别一上来就搞大工程。如果你后续想深入建议往事件循环机制、信号与槽的连接方式、Model/View 框架这几个方向继续看。PyQt6 的能力远不止弹个窗做小型工具软件、上位机界面、甚至多媒体播放器它都能胜任希望这篇教程能帮你顺利进门。