PyQt5 环境搭建保姆级教程：PyCharm + QtDesigner + PyUIC 完整配置

文章目录

一、前言
[二、安装 PyQt5 与 PyQt5-tools](#二、安装 PyQt5 与 PyQt5-tools)
- [2.1 安装 PyQt5](#2.1 安装 PyQt5)
- [2.2 安装 Qt 相关的工具包](#2.2 安装 Qt 相关的工具包)
[三、在 PyCharm 中配置外部工具](#三、在 PyCharm 中配置外部工具)
- [3.1 配置 QtDesigner](#3.1 配置 QtDesigner)
- [3.2 配置 PyUIC](#3.2 配置 PyUIC)
- [3.3 使用流程](#3.3 使用流程)
[四、Qt 常用控件介绍](#四、Qt 常用控件介绍)
五、快速上手
六、总结

一、前言

在当今的软件开发中，图形用户界面（GUI）已经成为桌面应用程序不可或缺的一部分。一个美观、易用的界面，往往能极大提升用户的使用体验。而 PyQt5 正是 Python 生态中最成熟、最强大的 GUI 开发框架之一。

PyQt5 是 Qt5 框架的 Python 绑定版本，由 Riverbank Computing 开发并维护。它完整继承了 Qt 跨平台、高性能、组件丰富的特性，同时兼具 Python 语言简洁易读的语法优势。借助 PyQt5，开发者可以：

快速构建桌面应用：从简单的工具软件到复杂的管理系统，PyQt5 都能胜任；
实现跨平台运行：同一套代码可在 Windows、macOS、Linux 等系统上运行，无需大幅修改；
使用可视化设计器：通过 QtDesigner 拖拽控件即可完成界面布局，大幅降低开发门槛；
结合信号与槽机制：轻松实现控件之间的交互与事件响应，逻辑清晰、易于维护；
访问丰富的控件库：按钮、文本框、表格、树形视图、图表等一应俱全，满足各类界面需求。

此外，PyQt5 还支持多线程、网络通信、数据库操作、多媒体播放等高级功能，能够帮助开发者构建功能完备的桌面应用。无论是学生做课程设计、开发者做内部工具，还是企业开发商业软件，PyQt5 都是一个非常值得掌握的选择。

二、安装 PyQt5 与 PyQt5-tools

2.1 安装 PyQt5

PyQt5 是 Qt5 框架的 Python 绑定，是开发图形界面程序的核心库。在 PyCharm 的终端（Terminal）中执行：

bash 复制代码

pip install PyQt5 -i https://mirrors.aliyun.com/pypi/simple/

2.2 安装 Qt 相关的工具包

PyQt5-tools 提供了 Qt 的辅助工具（如 QtDesigner 可视化设计器），安装命令如下：

bash 复制代码

pip install PyQt5-tools -i https://mirrors.aliyun.com/pypi/simple/

三、在 PyCharm 中配置外部工具

安装完依赖后，为了让 PyCharm 能直接调用 QtDesigner （可视化界面设计器）和 PyUIC（将 .ui 文件转换为 Python 代码）这两个外部工具，需要在 PyCharm 中进行配置。

配置入口：File（文件）→ Settings（设置）→ Tools（工具）→ External Tools（外部工具） ，点击左上角的 "+" 号新建工具。

3.1 配置 QtDesigner

在 "Edit Tool" 窗口中填写以下内容：

配置项	填写内容
Name（名称）	QtDesigner
Group（组）	外部工具
Program（程序）	`D:\zrq\Programming\Python3.11.9\Lib\site-packages\qt5_applications\Qt\bin\designer.exe`
Arguments（实参）	（留空）
Working directory（工作目录）	$FileDir$

说明：

designer.exe 是 Qt 自带的界面设计器程序路径，具体路径以你本机实际安装位置为准（新版 PyQt5-tools 一般位于 qt5_applications\Qt\bin\ 目录下）。

$FileDir$ 是 PyCharm 提供的宏，表示当前文件所在的目录，这样打开设计器后会定位到当前项目目录。

配置完成后点击 OK ，即可在菜单 Tools（工具）→ External Tools 中看到并启动 QtDesigner。

3.2 配置 PyUIC

PyUIC 的作用是将 QtDesigner 生成的 .ui 文件转换成可以直接在 Python 中使用的 .py 文件。同样在 "Edit Tool" 窗口中填写：

配置项	填写内容
Name（名称）	PyUIC
Group（组）	外部工具
Program（程序）	`D:\zrq\Programming\Python3.11.9\python.exe`
Arguments（实参）	`-m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.py`
Working directory（工作目录）	$FileDir$

配置项说明：

Program：指向你的 Python 解释器路径（注意换成你本机实际路径）。
Arguments 中的参数含义：
- -m PyQt5.uic.pyuic：调用 PyQt5 提供的 uic 模块（即 pyuic 工具）；
- $FileName$ ：当前选中的 .ui 文件；
- -o $FileNameWithoutExtension$.py：输出一个与 .ui 文件同名的 .py 文件。

3.3 使用流程

在 PyCharm 中通过外部工具启动 QtDesigner ，拖拽控件绘制界面，保存为 .ui 文件；
选中该 .ui 文件，右键 → External Tools → PyUIC ，即可自动生成对应的 .py 文件；
在代码中导入并运行生成的 .py 文件即可显示窗口。

四、Qt 常用控件介绍

QtDesigner 的左侧控件面板中提供了大量常用控件，下面是初学者最先需要掌握的 4 个基础控件：

控件	英文名称	功能说明
按钮	Push Button	点击后触发事件，是最常用的交互控件
单行文本框	Line Edit	只能输入单行文本，适合用户名、密码等输入
多行文本框	Text Edit	可输入多行文本，适合备注、正文等内容
标签	Label	用于显示静态文本或图片，不可交互

五、快速上手

右击项目目录，点击外部工具 → QtDesigner

点击 Create（创建）

自行设计界面并保存

右击保存好的.ui 文件，点击外部工具 → PyUIC，通过 PyUIC 将 .ui 转成 .py

新建一个.py文件,示例代码如下：

python 复制代码

from PyQt5 import QtCore, QtGui, QtWidgets  # 导入PyQt5的主要模块
from PyQt5.QtCore import *                 # 导入QtCore模块的所有内容，用于核心功能
from PyQt5.QtGui import *                  # 导入QtGui模块的所有内容，用于图形功能
from PyQt5.QtWidgets import QFileDialog, QMainWindow, QMessageBox  # 导入QtWidgets模块中的一些特定类

# from win1 import Ui_MainWindow  # 导入UI类，这个类包含了你的主窗口设计
from win1 import Ui_Dialog
import sys   # 导入系统模块，用于访问命令行参数和系统相关功能

class PyQtMainEntry(QMainWindow, Ui_Dialog):  
    def __init__(self):  # 构造函数
        super().__init__()  # 调用基类的构造函数进行初始化
        self.setupUi(self)  # 调用setupUi方法，根据Ui_MainWindow设计设置界面
        # 参数初始化

if __name__ == "__main__":
    app = QtWidgets.QApplication(sys.argv)  # 创建应用程序实例
    window = PyQtMainEntry()  # 创建主窗口实例
    window.show()  # 显示主窗口
    sys.exit(app.exec_())  # 进入事件循环，并确保在退出时清理

将代码from win1 import Ui_Dialog和class PyQtMainEntry(QMainWindow, Ui_Dialog)中的 win1、Ui_Dialog 改为自己.py文件中的内容。

运行后即可看到 QtDesigner 中设计的界面窗口：

六、总结

本文介绍了 PyQt5 图形界面开发环境的完整搭建过程：

安装依赖 ：通过 pip 安装 PyQt5 和 PyQt5-tools；
配置外部工具：在 PyCharm 的 External Tools 中配置 QtDesigner 与 PyUIC，实现可视化设计与代码转换的无缝衔接；
认识控件：了解了按钮、文本框、标签等基础控件的用途；
快速上手：通过一个完整的示例，走通了"QtDesigner 设计界面 → 保存 .ui 文件 → PyUIC 转换为 .py 文件 → 编写入口代码 → 运行显示窗口"的全流程；