这段时间好几个读者私信问我同一个问题Windows上到底怎么装PyQt6有的卡在Python环境有的装完了运行报错还有的不知道PyQt6跟PyQt5到底该选哪个。我干脆把从零到跑通第一个窗口的完整过程整理出来尽量说人话你照着操作就行。这篇教程的目标很简单让一个完全没接触过PyQt6的Windows用户在半小时内把环境装好、把第一个窗口程序跑起来顺便搞明白后面该学什么。文章里我会把每个步骤背后的原因讲清楚不会只丢一堆命令让你复制粘贴。无论你是刚学Python、想给脚本加个界面还是准备做点小工具给同事用这套流程都适用。1. 为什么选PyQt6先搞懂你在装什么东西1.1 PyQt6到底是个啥玩意PyQt6是Qt 6框架的Python绑定。简单理解就是Qt是一套用C写的、非常成熟的GUI图形用户界面开发框架而PyQt6让你可以直接用Python调用这套框架用几行代码就做出带按钮、输入框、表格、标签页的桌面程序。Windows上做桌面界面可选方案其实不少Tkinter是Python自带的简单但丑Electron用Web技术做界面体积大、内存占用高PyQt6则在这两者之间找到了很好的平衡——界面原生、控件丰富、文档多、生态成熟而且写出来的程序跨平台Windows和Linux都能跑。我用PyQt6做过内部工具、数据报表程序、模拟器面板说实话日常能想到的桌面需求它几乎都覆盖了。更关键的是有Qt Designer这种可视化设计工具拖拽控件生成界面再用代码去写业务逻辑开发效率比纯手写坐标高太多。1.2 为什么推荐PyQt6而不是PyQt5或PySide6这是很多人纠结的第一个问题。我的建议很明确新项目直接上PyQt6除非你维护的是老项目。PyQt5是老一代版本对应Qt 5API相对稳定网上教程最多。但Qt 5已经停止维护新特性都不再更新了。PyQt6是Qt 6的绑定底层的C框架做了大量架构调整性能和渲染都在提升我个人实测高分屏支持、字体渲染都明显比PyQt5顺滑。那PySide6又是什么它是Qt官方推出的Python绑定跟PyQt6的API非常像。两者最大的区别在许可证PyQt6是GPL协议你有义务把基于它开发的代码开源PySide6是LGPL协议商用和闭源更友好。如果你是个人学习或内部工具PyQt6完全够用如果要商业化分发可以考虑PySide6。从代码写法上区分意义不大学会了任一个切到另一个也就是改几个import的事。用PyQt6还有一个容易忽略的好处新教程、新第三方库都在往Qt 6迁移现在学PyQt5等于是在学一套逐渐过时的API过两年还是要再搬一遍。不如直接一步到位。1.3 安装前要确认的两件事Windows版本和Python版本先说系统。PyQt6支持Windows 10和Windows 1164位系统为主流。Win7我劝你放弃Qt 6官方早就放弃了对Win7的支持装了也可能出现各种诡异问题。再说Python版本。PyQt6要求Python 3.7以上但2024年之后的新版本基本都朝Python 3.9走。实操中我建议直接用Python 3.10或3.12既不会太老缺特性也不至于太新导致某些第三方库还没跟上。64位Python是必须的32位环境和PyQt6的轮子包经常对不上。判断自己机器的Python版本后面第二步会详细说但你只需要记住系统版本符合要求、Python版本在3.9以上、位数32/64匹配接下来的安装就是一条命令的事。2. Python环境准备把地基打好2.1 检查电脑上有没有Python这一步强烈建议你先做再装否则容易搞出多个Python环境互相打架的局面。按Win R输入cmd回车打开命令行窗口输入python --version如果显示类似Python 3.12.2这样的版本号说明已经装好了直接跳到第3节。如果提示python 不是内部或外部命令说明没装或者没加到PATH环境变量里往下看。还有可能遇到一种情况输入python后没有反应或者自动打开了Microsoft Store。这是因为Windows的App执行别名把python这个命令拦走了。这种情况下建议直接去Python官网下载安装包后面会自动覆盖处理。2.2 安装Python时最容易踩的坑忘记勾选Add to PATH去Python官网python.org/downloads下载最新稳定版打开安装包后第一屏会有一个复选框写着Add Python to PATH这里一定要勾上这是我见过新手最常翻车的地方没有之一。PATH是什么你可以把它理解成Windows的寻人启事——当你在命令行里输入一个命令Windows会按PATH里记的路径挨个去找这个程序。不勾Add to PATH系统就找不到Python后来你在命令行怎么敲python都是无效的。安装方式选Install Now就行它会自动装到当前用户目录下权限问题少。如果你需要改安装路径选Customize installation也可以但路径不要带中文和空格否则后续pip装一些带编译的包容易出莫名奇妙的错误。2.3 验证Python和pip是否可用装完Python重新开一个命令行窗口注意是重新开别在旧窗口里敲环境变量不会自动刷新然后依次确认python --version pip --versionpip是Python的包管理工具PyQt6就是通过它来安装的。如果pip --version提示找不到试试python -m pip --versionpython -m pip这种写法会明确用当前Python环境里的pip模块本质上是先通过python定位到解释器再让它执行pip。这种写法能一定程度避免多Python环境下命令到模块不匹配的混乱局面我建议你后面装PyQt6也统一用这种写法。最后顺手把pip升级一下python -m pip install --upgrade pippip版本太旧下载依赖时解析慢不说偶尔还会因为老版本bug导致安装失败。反正这步没有副作用升就完事了。到这里环境部分就算准备妥当。整个过程的核心其实是把PATH和pip确认好这两样不出问题后面就是一路顺畅。3. 安装PyQt6最核心的一步3.1 用pip安装PyQt6主库打开命令行直接执行下面这条命令python -m pip install PyQt6pip会自动去PyPIPython官方软件仓库下载PyQt6的安装包同时会把依赖的PyQt6-Qt6、PyQt6-sip一起装上。这几个名字你可能会在输出里看到不用担心它们都是PyQt6正常运行需要的基础组件Qt6是真正的C库本体sip是Python和C之间通信的胶水层。整个安装从几十秒到几分钟不等取决于你的网络情况。看到类似Successfully installed PyQt6-6.7.x PyQt6-Qt6-6.7.x PyQt6-sip-13.x.x的字样就是装好了。国内网络下载PyPI经常速度感人如果你发现一直卡在进度条可以换成国内镜像源比如清华、阿里、豆瓣任选一个python -m pip install PyQt6 -i https://pypi.tuna.tsinghua.edu.cn/simple加-i参数的意思是临时指定源地址。镜像源和官方源的内容保持一致更新可能稍慢但不影响正常使用。3.2 安装Qt Designer可视化设计工具安装完PyQt6主库后你其实已经可以写代码建界面了。但小白阶段我强烈推荐再装一个Qt Designer它是一个可视化的界面拖拽工具可以让你像画图一样把按钮、文本框放到窗口上然后自动生成对应的.ui文件再把这个文件转成Python代码。最常见的安装方法是python -m pip install PyQt6-tools但这里必须说句实在话PyQt6-tools这个包在部分环境里存在兼容性问题装完可能找不到designer.exe或者版本很老。我自己在个别Python版本比如3.12的某些小版本上就遇到过依赖冲突装上之后命令行里敲designer提示找不到命令。如果你遇到这种情况我的建议是不要死磕pip直接换一条路到第三方PyQt镜像站下载独立的Qt Designer安装包解压即用。这种方法其实更简单——Qt Designer只是设计工具不需要跟Python环境深度绑定。装完直接生成.ui文件后续用脚本转成.py就行完全不影响开发。对于纯代码入门、不想装额外工具的同学跳过这一步也没问题后面我会示范不依赖Designer的代码建界面方式。3.3 验证PyQt6是否安装成功这一步值得认真做。装完之后别急着写大工程你先在命令行里敲python进入交互模式连按Ctrl Z再回车可以退出然后逐行输入from PyQt6.QtWidgets import QApplication, QWidget import sys app QApplication(sys.argv) win QWidget() win.setWindowTitle(安装成功) win.resize(300, 200) win.show() sys.exit(app.exec())如果代码不报错屏幕上弹出一个写着安装成功的小窗口说明PyQt6已经完整可用。这也是PyQt6程序的标准骨架创建QApplication - 创建窗口 - 设置标题和大小 - 显示窗口 - 进入事件循环。有的同学在这里会卡住提示ModuleNotFoundError: No module named PyQt6。这个99%的情况是Python环境不对——你装了包的环境和运行代码的环境不是同一个或者压根装错Python版本了。排查思路我在第6节详细展开你先记住一个原则用python -m pip装就用同一套python运行别混。验证完这一步你的PyQt6环境就算正式落地了。接下来可以写点真正能看的程序。4. 第一个PyQt6程序从空窗口到能交互4.1 最简单可运行的窗口代码新建一个main.py文件目录随意别带中文路径就行把下面的代码复制进去。我特意把代码写得比空窗口稍微丰富一点既不会复杂到让你劝退又能一次感受到PyQt6的几个核心概念。import sys from PyQt6.QtWidgets import QApplication, QMainWindow, QPushButton, QLabel, QVBoxLayout, QWidget class MainWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle(我的第一个PyQt6程序) self.resize(500, 350) # 创建一个按钮和一个标签 self.button QPushButton(点我一下) self.label QLabel(这里会显示结果) # 用垂直布局把控件排成一列 layout QVBoxLayout() layout.addWidget(self.label) layout.addWidget(self.button) # 中心组件承载布局 container QWidget() container.setLayout(layout) self.setCentralWidget(container) # 绑定按钮点击事件 self.button.clicked.connect(self.on_click) def on_click(self): self.label.setText(按钮被点击了) if __name__ __main__: app QApplication(sys.argv) window MainWindow() window.show() sys.exit(app.exec())4.2 代码逐段解释这段代码看着不多但里面已经是PyQt6最经典的套路了。我拆开讲一下你理解之后后面自己改东西就不懵。QApplication代表整个应用程序本身每个PyQt6程序必须创建且只能创建一个。它负责管理事件循环和全局设置相当于整个程序的发动机。QMainWindow是主窗口类它自带菜单栏、状态栏、工具栏的框架结构。作为对比前面验证用的是QWidget就是一个空白的裸窗口QMainWindow是带有完整骨架的窗口真实项目里更常用。QVBoxLayout是垂直布局管理器。PyQt6的布局机制要注意你没法直接把控件放到窗口上指定坐标那样做也行但尺寸一变就乱套正确做法是把控件往布局里塞布局再塞进一个容器组件最后setCentralWidget挂到主窗口上。这套嵌套思想是PyQt6布局的核心初期可以先照抄后面慢慢体会。button.clicked.connect(self.on_click)这行是信号槽机制。clicked是按钮内置的信号表示用户点击了这个按钮connect把这个信号连接到on_click方法上相当于说用户点了就去执行这个方法。这是PyQt6事件处理的核心比传统GUI框架的回调函数要优雅得多。4.3 运行结果与常见运行问题在命令行窗口进入main.py所在目录执行python main.py应当看到一个500x350大小的窗口中间有一个标签和一个按钮。点击按钮标签文字从这里会显示结果变成按钮被点击了。新手在跑这类程序时最常遇到两个现象我提前打个预防针第一个窗口一闪而过然后直接消失。这种情况十有八九是你用了类似IDLEPython自带的编辑器的运行模块功能或者代码里漏了app.exec()这一行。app.exec()是事件循环的入口它让程序进入等待用户操作的状态直到你关闭窗口才结束。没有这一行程序跑完就退出窗口自然瞬间消失。务必确保代码完整并且用命令行python main.py方式运行。第二个中文标题显示成乱码方块。PyQt6本身对UTF-8友好正常情况下不会出现这个现象。如果你真的遇到了先确认Python文件保存的编码是UTF-8主流编辑器右下角能看编码格式再不行就在代码开头加# -*- coding: utf-8 -*-虽然Python 3默认就是UTF-8加上也不会有坏处。窗口能跑起来、按钮能响应事件你对PyQt6的基本工作流程就算通关了。接下来我讲几个跟实际开发强相关的配置帮你把效率提上去。5. 写代码之外的工具配置从入门到顺手5.1 在编辑器里配置PyQt6环境代码写多了你自然会发现光靠记事本开发效率太低。推荐用VS Code免费、插件多、对Python支持好。装好Python插件后按Ctrl Shift P搜索Python: Select Interpreter选你已经安装PyQt6的那套Python解析器。这一步很重要。如果你的VS Code选了解释器但选的是一个没装PyQt6的Python环境运行代码时依然会报ModuleNotFoundError。特别是机器上装过Anaconda、或者存在多个Python版本的人最容易在这种地方翻车。PyCharm的用户在File - Settings - Project - Python Interpreter里同样选择对应的环境即可。另外建议装一个PyQt6的辅助插件VS Code搜PYQT Integration它会帮你高亮.ui文件。这类插件主要提供代码补全和模板生成装上能减少一半键盘输入量。5.2 Qt Designer生成的ui文件怎么用用Qt Designer拖出一张界面后会保存成一个.ui文件。这个文件本质是XML格式的界面描述不能直接运行需要转成Python代码才能用。打开命令行执行python -m PyQt6.uic.pyuic input.ui -o output.pyPyQt6.uic.pyuic是PyQt6自带的UI编译器-o指定输出文件名。转换成功后你会得到一个继承自QMainWindow或QWidget的类里面包含了界面的初始化和控件布局代码。在自己的主程序里导入这个类实例化就能用。注意转换出来的output.py不应该手动修改因为一旦你在Designer里改了界面又转一次之前的改动就全丢了。正确做法是output.py管界面主程序管逻辑两者严格分离。这是所有Qt项目的黄金法则越早养成习惯越省心。5.3 打包成exe文件给没有Python的电脑用工具做出来最终是要给别人用的但对方的电脑上不一定装了Python这时就需要把程序打包成独立的exe。PyInstaller是这方面最流行的工具安装和使用都很简单python -m pip install pyinstaller然后在项目目录下执行python -m PyInstaller -w -F main.py我来解释一下这两个关键参数-w表示打包窗口程序运行时不要弹出黑色的命令行窗口-F表示打包成单个exe文件。打包完成后在dist文件夹里能找到main.exe直接双击就能运行。我踩过的一个坑如果你的程序里用了图片、音效等外部资源文件需要额外处理。比如把资源文件放到exe同目录或者用PyInstaller --add-data参数把资源打包进去。具体做法是python -m PyInstaller -w -F --add-data assets;assets main.py--add-data后面第一个参数是源文件路径第二个参数是打包后在临时目录里的路径Windows上用英文分号分隔。但这里先提醒你程序里读取资源的路径也要跟着调整否则打包后找不到文件。用sys._MEIPASS这个变量只在打包后存在拼接临时目录路径这是PyInstaller的通行做法。打包这块水比安装深得多但你不一定要立刻全学完。先把本机能跑通后面有需要再逐项深入。6. 常见问题与排查技巧把我踩过的坑直接给你6.1 pip安装超时或下载速度慢这是国内网络环境的通病。现象是pip卡在Downloading那一步半天不动或者报Read timed out错误。处理方案前面提过换镜像源python -m pip install PyQt6 -i https://pypi.tuna.tsinghua.edu.cn/simple如果一次换源还不行可以加两个参数增加容错python -m pip install PyQt6 -i https://pypi.tuna.tsinghua.edu.cn/simple --timeout 120--timeout 120把每次请求超时时间拉长到120秒对不稳定网络很管用。下载完再装的时候失败多数是网络抖动重试一次就好了。6.2 ModuleNotFoundError: No module named PyQt6这是所有新手挫折感的来源但原因其实就那么几个对号入座第一个pip装和运行的环境不一致。你可能用pip install装却用另一个Python运行代码。解决办法统一都用python -m pip来装运行也用同一个python。至少在命令行里执行where pythonWindows查看实际用的是哪个路径再执行python -c import PyQt6; print(PyQt6.__file__)看模块装到了哪里两边一对照就知道是不是同一个。第二个装到了用户级环境但代码运行在系统环境。这种情况常见于多用户电脑。在命令行里查一下pip show PyQt6的Location字段和python实际模块搜索路径对比即可。第三个虚拟环境venv没激活。现在很多人习惯用虚拟环境来隔离项目依赖但虚拟环境跟全局环境是两套系统在A环境装包、在B环境运行注定报错。如果你用虚拟环境务必先激活再操作。6.3 程序运行报错This application failed to start because no Qt platform plugin could be initialized这个报错我看到过很多次很多第一次用PyQt6的人见到大红字就慌了以为是自己的代码有问题。其实不是。在Windows上PyQt6运行需要Qt平台插件比如Windows平台插件如果它在寻找这些插件时找不到就会报这个错。常见原因有两个一是打包时漏掉了插件目录解决方法是确保PyInstaller能自动收集到Qt插件某些情况下需要在.spec文件里手动添加二是你手工修改过PyQt6的安装目录破坏了插件和主库的相对路径。我的建议如果你是开发阶段遇到优先检查Python和PyQt6是否为64位一致如果是打包后遇到先确保exe和platforms目录、Qt相关DLL在同目录或者正确打包实在不行用管理员身份重新安装一次Visual C Redistributable这个运行库缺失也会触发类似报错。6.4 明明显示了Requirement already satisfied代码却还是找不到PyQt6这个现象背后有个很容易忽略的逻辑pip说满足要求只能证明当前这个pip所对应的环境里有这个包不代表所有Python环境都有。举个例子假设电脑上装了Anaconda的Python又装了官方Python。你在Anaconda的终端里敲pip install PyQt6它装的是Anaconda环境的但你后来用VS Code选择了官方Python解释器那运行代码时自然找不到。解决办法关闭所有终端重开在VS Code里按Ctrl Shift P重新选择正确的Python解释器。或者干脆用虚拟环境把一切变量都锁死。我个人的习惯是每个项目一个venvvenv里只装项目需要的依赖所有包都是明明白白的踩重复环境的坑大大减少。6.5 中文字体显示为方块或模糊PyQt6对中文的支持整体不错但某些系统字体缺失时会显示成方块。解决方式有两种第一种是系统级在Windows的设置 - 个性化 - 字体里安装微软雅黑或宋体一般默认就有。第二种是代码级设置全局字体from PyQt6.QtGui import QFont font QFont(Microsoft YaHei, 10) app.setFont(font)但这行代码要在QApplication创建之后调用否则不生效。字体模糊问题通常和屏幕缩放有关PyQt6在高DPI屏幕上表现已经比PyQt5好很多如果还觉得模糊可以设置Qt的分辨率策略为自动感知app.setAttribute(Qt.ApplicationAttribute.AA_EnableHighDpiScaling, True)注意这段代码必须在创建窗口之前执行。这些都属于界面细节不影响功能真遇到再折腾。我实际操作下来Windows上装PyQt6并不存在真正的难点大部分人的问题都集中在环境不一致这四个字上。所以不管你是正装的还是遇到报错了第一步永远是检查我的Python是哪一个包装在哪个环境运行代码用的又是哪个环境三个对上了问题就解决了一大半。最后再说个实用的小技巧如果你在家里的电脑上装好了PyQt6又想在公司电脑上快速部署同一个环境可以生成一个requirements文件python -m pip freeze requirements.txt到另一台机器上执行python -m pip install -r requirements.txt依赖版本就被原样还原了。这招在备份、换机、给别人搭环境时特别省心我自己已经用烂了。环境搭好了就赶紧动手写个带界面的小工具吧别光看教程PyQt6这东西跑起来一个窗口比读十篇文章管用。