Python Qt新手入门：安装库并创建第一个GUI窗口

Theo

发布时间：2026-11-11 | 4人浏览过

原创

面向Python初学者的Qt图形界面入门教程，详细讲解PySide6/PyQt库的选择与安装步骤，解析QApplication与QWidget核心机制，手把手带你编写并运行第一个桌面GUI窗口。

分类：Python GUI 开发适用对象：初学者 / 桌面应用开发入门

Python Qt新手入门：安装库并创建第一个GUI窗口 — 图 0：从 Python 源码到首个 Qt 桌面窗口的运行映射

使用 Python 构建桌面图形界面（GUI）时，Qt 凭借成熟的跨平台支持和丰富的原生控件成为主流选择。本文的目标非常明确：帮助初学者理清 Python Qt 库的选择依据，在本地完成依赖库的安装与环境验证，并用最简洁的标准代码创建并展示你的第一个桌面窗口。

一、库的选择：PySide6 还是 PyQt6？

初学者在搜索 Python Qt 时，往往会同时看到 PySide 和 PyQt 两个名词。它们都是 Qt 框架在 Python 上的官方或第三方绑定，但底层背景和许可证有所差异：

PySide6（推荐）：Qt 官方团队（The Qt Company）直接维护的 Python 绑定，遵循 LGPL 协议。这意味着即便开发商业闭源软件，只要动态链接库即可免费使用，无需购买商业授权。
PyQt6：由 Riverbank Computing 公司开发的成熟第三方绑定，遵循 GPL 协议。如果用于商业闭源产品，必须购买其商业授权，否则源码也须按 GPL 开源。

两者在 API 语法上有 95% 以上的一致性。对于新手，直接选择官方支持且授权宽松的 PySide6 是最省心、标准的选择。

二、环境准备与库安装

在安装 PySide6 之前，请确保本地已安装 Python 3.8 或更高版本（Qt 6 要求 Python 3.8+）。为了避免全局依赖冲突，强烈建议在独立的虚拟环境中操作。

步骤 1：创建并激活虚拟环境

打开终端（Windows 下可使用 PowerShell 或 CMD，macOS/Linux 使用 Terminal），进入你的工作目录并执行：

# 创建名为 qt_env 的虚拟环境
python -m venv qt_env

# 激活虚拟环境
# Windows (PowerShell):
qt_env\Scripts\Activate.ps1

# Windows (CMD):
qt_env\Scriptsctivate.bat

# macOS / Linux:
source qt_env/bin/activate

步骤 2：使用 pip 安装 PySide6

在激活的虚拟环境中，直接使用官方包管理器 pip 安装：

pip install PySide6

如果下载速度较慢，可以临时使用国内常用镜像源加速安装：

pip install PySide6 -i https://pypi.tuna.tsinghua.edu.cn/simple

步骤 3：验证安装是否成功

安装完成后，可以在命令行中快速检验模块是否能正常导入并输出当前版本号：

python -c "import PySide6; print(PySide6.__version__)"

如果能够正常打印出版本号（如 6.7.x 或更高版本），说明库已就绪。

三、创建第一个基础 GUI 窗口

一个合法的 Qt GUI 程序至少需要满足两个基本要素：

一个负责管理控制流和全局设置的 QApplication 实例；
至少一个顶层窗口组件（如 QWidget 或 QMainWindow），并通过 show() 方法使其可见。

新建一个名为 first_window.py 的文件，写入以下完整代码：

import sys
from PySide6.QtWidgets import QApplication, QWidget

# 1. 创建应用程序对象
app = QApplication(sys.argv)

# 2. 创建顶层窗口部件
window = QWidget()
window.setWindowTitle("我的第一个 Qt 窗口")
window.resize(400, 300)

# 3. 展现窗口
window.show()

# 4. 开启 Qt 主事件循环
sys.exit(app.exec())

逐行原理解释

这段代码虽然仅有 10 行，却涵盖了所有桌面应用的核心生命周期：

from PySide6.QtWidgets import QApplication, QWidget：从控件库中按需引入核心管理类与基础窗口部件。
app = QApplication(sys.argv)：必须在创建任何窗口部件前实例化。它负责初始化图形子系统、屏幕参数，并接管命令行参数 sys.argv。在同一个进程中，QApplication 必须且只能实例化一次。
window = QWidget()：没有指定父级（parent）的 QWidget 将自动被操作系统视作独立顶级窗口。
window.setWindowTitle(...) 与 window.resize(400, 300)：设置窗口标题栏文字以及初始长宽（像素单位）。
window.show()：在 Qt 中，新建的窗口默认处于隐藏状态，显式调用 show() 才会通知操作系统视窗管理器将其绘制出来。
sys.exit(app.exec())：进入 Qt 的无限事件循环（Event Loop）。程序会停留在这一行，持续监听并分发鼠标点击、键盘按键和窗口缩放等系统事件；当用户点击右上角关闭按钮退出应用时，app.exec() 返回退出代码并传给 sys.exit() 优雅终结 Python 进程。

四、添加交互元素：按钮与信号槽机制

空窗口只是骨架，真实应用需要添加控件（Widget）以及响应用户操作。在 Qt 中，控件间的交互是通过核心的 信号与槽（Signals and Slots） 机制实现的：

信号（Signal）：当特定事件发生时由控件发出，例如按钮被按下发出 clicked 信号。
槽（Slot）：用于接收并响应信号的普通 Python 函数或方法。

下面我们将窗口代码重构为面向对象写法（生产环境标准模式），并添加标签、按钮及点击计数功能：

import sys
from PySide6.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel, QPushButton
from PySide6.QtCore import Qt

class MainWindow(QWidget):
    def __init__(self):
        super().__init__()
        self.count = 0

        # 设置窗口基础属性
        self.setWindowTitle("交互式 Qt 计数器")
        self.resize(320, 200)

        # 1. 创建控件
        self.label = QLabel("当前点击次数：0", self)
        self.label.setAlignment(Qt.AlignCenter)
        self.label.setStyleSheet("font-size: 16px; color: #2C3E50; margin: 10px;")

        self.button = QPushButton("点我计数", self)
        self.button.setStyleSheet("padding: 8px 16px; font-size: 14px; background-color: #6B88A6; color: white; border-radius: 4px;")

        # 2. 绑定信号与槽函数
        self.button.clicked.connect(self.on_button_clicked)

        # 3. 使用垂直布局管理器
        layout = QVBoxLayout()
        layout.addWidget(self.label)
        layout.addWidget(self.button)
        self.setLayout(layout)

    def on_button_clicked(self):
        self.count += 1
        self.label.setText(f"当前点击次数：{self.count}")

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec())

面向对象封装的优势：将窗口继承自 QWidget 并在 __init__ 中初始化，可以很方便地用 self 统一持有各控件的引用，防止变量因作用域结束被 Python 垃圾回收机制（GC）销毁。

五、新手入门常见问题与避坑指南

在初次运行 Python Qt 脚本时，以下几个问题最为常见：

常见现象 / 报错	原因分析	解决方法
`QWidget: Must construct a QApplication before a QWidget`	在未实例化 `QApplication` 之前就直接创建了窗口组件或全局控件。	确保 `app = QApplication(sys.argv)` 始终位于任何界面控件创建之前。
程序一闪而过，窗口没有显示	脚本结尾漏掉了 `app.exec()`，或者窗口变量在函数内部未保持引用被 GC 销毁。	确保主程序最后调用了 `app.exec()`；若在函数中创建窗口，请赋值为全局变量或类属性。
PySide2 与 PySide6 混淆混用	网络上旧教程多采用 Qt5（PySide2），与 Qt6 存在部分模块路径调整。	认准 `PySide6`，旧代码中 `exec_()` 在 PySide6 中可直接写作标准 Python 语法的 `exec()`。
高分屏缩放模糊	Qt 6 已默认开启高分屏 DPI 自动缩放，无需像 Qt 5 那样手动配置属性。	直接使用 PySide6 最新版本即可享受原生高质量缩放。

结语

通过本文的操作，你已经完成了 Python Qt 官方推荐库 PySide6 的安装，理清了 QApplication 与窗口部件的分工，并成功运行了一个具备事件循环和交互能力的 GUI 窗口。以此为起点，后续你可以进一步学习 Qt Designer 可视化拖拽布局，或探索多线程（QThread）处理耗时任务，逐步构建出结构更完整、体验更流畅的桌面级应用。