PyQt5入门实战：安装、QtDesigner设计与PyUIC转换完整指南

PyQt5 入门实战：安装、QtDesigner 设计与 PyUIC 转换完整指南

环境说明：Python 3.9 + PyQt5 5.15.4 + PyCharm（Community/Professional 均适用）

---

一、什么是 PyQt5？

PyQt5 是 Qt5 框架的 Python 绑定，由 Riverbank Computing 基于 SIP（C++ 桥接工具）封装。它让 Python 开发者可以用纯 Python 代码构建功能完整的跨平台桌面 GUI 应用。

1.1 核心特点

特点	说明
跨平台	一套代码运行在 Windows / macOS / Linux
控件丰富	数百种原生控件，外观与操作系统一致
可视化设计	配套 Qt Designer 拖拽设计界面，无需手写布局代码
信号槽机制	独特的事件通信系统，松耦合，易维护
免费开源	GPL 协议开源，商业用途需购买授权

1.2 PyQt5 架构总览

架构分三层：

• Python 应用层 ：开发者编写的 .py 业务逻辑代码
• PyQt5 绑定层：SIP 负责 Python 调用 C++ Qt 的桥接
• Qt5 底层：C++ 实现的高性能 UI 引擎

---

二、安装 PyQt5

2.1 相关包说明

安装 PyQt5 时需要关注以下几个包（以截图中实际版本为例）：

包名	版本	作用
pyqt5	5.15.4	核心包，包含所有 Qt 控件 Python 绑定
pyqt5-tools	5.15.4.3.2	工具包，含 Qt Designer 可执行文件
pyqt5-qt5	5.15.2	Qt5 运行时 C++ 动态库
pyqt5-sip	12.17.1	SIP 桥接层，Python 调用 C++ 的核心组件

2.2 安装方法

方法一：PyCharm 图形界面安装（推荐新手）

1. 打开 PyCharm → 文件 → 设置 → 项目 → Python 解释器
2. 点击右侧 + 号
3. 搜索 pyqt5，勾选后点击安装软件包
4. 同理搜索安装 pyqt5-tools

方法二：pip 命令安装

pip install pyqt5 pyqt5-tools

提示：若下载较慢，可使用国内镜像加速：

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

2.3 验证安装

import PyQt5
print(PyQt5.QtCore.PYQT_VERSION_STR)  # 输出 5.15.4 表示安装成功

---

三、在 PyCharm 中配置外部工具

安装完成后需要在 PyCharm 中配置 QtDesigner 和 PyUIC 两个外部工具，后续便可一键启动设计器和转换 .ui 文件。

进入配置入口：

PyCharm → 文件 → 设置（Ctrl+Alt+S）→ 工具 → 外部工具 → 点击 + 号

---

3.1 配置 QtDesigner

在弹出的编辑工具对话框中填写以下内容：

字段	填写内容
名称	QtDesigner
程序	Qt Designer 可执行文件路径
实参	留空
工作目录	$FileDir$

如何找到 designer.exe 路径？

在 PyCharm 终端执行：

python -c "import qt5_applications; import os; print(os.path.dirname(qt5_applications.__file__))"

找到输出的目录后，拼接路径：

<输出目录>\Qt\bin\designer.exe

完整路径示例（根据你的实际虚拟环境路径调整）：

C:\Users\用户名\AppData\Local\Programs\Python\Python39\.venv\Lib\site-packages\qt5_applications\Qt\bin\designer.exe

截图中显示的路径末尾为 ...\site-packages\qt5_applications\Qt\bin\designer.exe，这是虚拟环境下的标准位置。

配置完成后，高级选项中勾选：

• ✅ 在执行后同步文件
• ✅ 打开工具输出的控制台

---

3.2 配置 PyUIC

PyUIC 用于将 Qt Designer 生成的 .ui 文件转换为 Python 代码（.py）。

字段	填写内容
名称	PyUIC
程序	当前虚拟环境的 python.exe 路径
实参	-m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.py
工作目录	$FileDir$

python.exe 路径示例：

C:\Users\用户名\AppData\Local\Programs\Python\Python39\.venv\Scripts\python.exe

实参说明：

• -m PyQt5.uic.pyuic：以模块方式调用 pyuic5
• $FileName$：当前选中的 .ui 文件名（PyCharm 宏变量）
• -o $FileNameWithoutExtension$.py：输出为同名 .py 文件

配置完成后效果 ：如截图所示，工具 → 外部工具 下会出现 QtDesigner 和 PyUIC 两个工具项。

---

四、启动 QtDesigner 设计 UI

4.1 启动方式

配置完成后，在 PyCharm 中：

工具 → 外部工具 → QtDesigner

成功后将弹出如下界面（Qt 设计师）：

Qt Designer 界面组成：

区域	说明
左侧 Widget Box	控件库，包含布局/按钮/输入框/列表等数百种控件
中央画布	设计区域，拖拽控件到此处
右上 对象查看器	显示界面中所有控件的树状结构
右中 属性编辑器	修改选中控件的属性（大小/字体/颜色等）
右下 资源浏览器	管理图片等资源文件

上图为成功启动后的 Qt 设计师界面，选择 Main Window 模板即可开始设计主窗口。

4.2 基本操作流程

1. 启动 QtDesigner，选择模板（MainWindow / Dialog / Widget）
2. 从左侧控件库拖拽控件到中央画布
3. 在右侧属性编辑器调整控件属性
4. Ctrl+S 保存为 .ui 文件（保存到 PyCharm 项目目录）

---

五、PyUIC 转换 .ui 为 .py

设计完 UI 后，通过 PyUIC 将 .ui 转换为 Python 代码：

1. 在 PyCharm 项目中右键 点击 .ui 文件
2. 选择 外部工具 → PyUIC
3. 同目录下会自动生成同名 .py 文件

转换后的 .py 文件结构：

# 由 PyUIC 自动生成，不要手动修改
from PyQt5 import QtCore, QtGui, QtWidgets

class Ui_MainWindow(object):
    def setupUi(self, MainWindow):
        MainWindow.setObjectName("MainWindow")
        MainWindow.resize(800, 600)
        # ... 所有控件的创建和布局代码

    def retranslateUi(self, MainWindow):
        # 文字内容设置（支持国际化）
        MainWindow.setWindowTitle("MainWindow")

---

六、完整开发工作流程

安装 PyQt5 + pyqt5-tools
        ↓
配置 PyCharm 外部工具（QtDesigner / PyUIC）
        ↓
启动 QtDesigner 拖拽设计界面
        ↓
保存为 .ui 文件
        ↓
右键 → PyUIC → 生成同名 .py 文件
        ↓
在主程序中导入 .py，绑定信号槽，运行程序

主程序调用示例：

import sys
from PyQt5.QtWidgets import QApplication, QMainWindow
from ui_mainwindow import Ui_MainWindow  # 导入 PyUIC 生成的文件

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.ui = Ui_MainWindow()
        self.ui.setupUi(self)
        # 在此绑定信号与槽
        self.ui.pushButton.clicked.connect(self.on_click)

    def on_click(self):
        print("按钮被点击！")

if __name__ == '__main__':
    app = QApplication(sys.argv)
    win = MainWindow()
    win.show()
    sys.exit(app.exec_())

---

七、常见问题

Q1：找不到 designer.exe？

确认已安装 pyqt5-tools，然后执行：

pip show pyqt5-tools

在 Location 路径下找 qt5_applications\Qt\bin\designer.exe。

Q2：PyUIC 运行后没有生成 .py 文件？

• 确认实参格式正确，注意 -m PyQt5.uic.pyuic 前后有空格
• 确认程序路径指向的是虚拟环境的 python.exe，不是系统 Python

Q3：QtDesigner 打开时报 DLL 错误？

重新安装 pyqt5-qt5：

pip install --force-reinstall pyqt5-qt5

Q4：生成的 .py 里中文显示乱码？

在文件头添加：

# -*- coding: utf-8 -*-

并确保 .ui 文件保存时使用 UTF-8 编码。

---

八、总结

工具	用途	关键路径/参数
pyqt5	核心 Python 绑定库	pip install pyqt5
pyqt5-tools	含 Qt Designer	pip install pyqt5-tools
QtDesigner	可视化拖拽设计 UI	...\qt5_applications\Qt\bin\designer.exe
PyUIC	.ui → .py 自动转换	-m PyQt5.uic.pyuic $FileName$ -o $FileNameWithoutExtension$.py

核心理念 ：PyQt5 将 UI 设计（.ui）与业务逻辑（.py）分离，QtDesigner 专注界面，Python 专注逻辑，是桌面 GUI 开发的高效实践。

---

下一篇预告 ：PyQt5 信号与槽机制详解 ------ 从按钮点击到自定义事件，彻底理解 Qt 的事件驱动模型。

\qt5_applications\Qt\bin\designer.exe| | **PyUIC** | .ui → .py 自动转换 |-m PyQt5.uic.pyuic FileNameFileNameFileName -o FileNameWithoutExtensionFileNameWithoutExtensionFileNameWithoutExtension.py` |

核心理念 ：PyQt5 将 UI 设计（.ui）与业务逻辑（.py）分离，QtDesigner 专注界面，Python 专注逻辑，是桌面 GUI 开发的高效实践。

---

下一篇预告：PyQt5 信号与槽机制详解 ------ 从按钮点击到自定义事件，彻底理解 Qt 的事件驱动模型。