如何在树莓派上用 PyQt 编写 Python 图形界面程序?

我做很多树莓派项目都会用到Python，尤其是在操控GPIO引脚、编写自动化小脚本的时候。可在终端里运行代码是一回事，给程序打造简洁易用的可视化窗口界面，则完全是另一回事。PyQt就是实现这个需求最简单的工具之一。

PyQt 是一套基于 Python 开发图形界面（GUI）的程序库。树莓派官方系统软件源里自带该库，可通过 APT 软件包管理器直接安装。 

本文会先通俗讲解 PyQt工作原理，一步步带你完成安装，并手把手写出你的第一个树莓派 GUI 桌面程序。

目录

• 什么是 PyQt？

• 树莓派安装 PyQt 教程

• 树莓派 PyQt 入门实操

---

什么是PyQt？

顾名思义，PyQt = Python + Qt 结合而成。

Python在树莓派中是默认主推的编程语言，预装在树莓派系统中，配套海量拓展库。

Qt是业界主流跨平台图形界面开发框架，底层用 C++ 编写，可运行在 Windows、Linux、macOS 乃至手机移动端所有系统上，专门用来制作带窗口、按钮、弹窗的桌面软件。

而 PyQt，就是让Python语言能够调Qt框架的工具包。核心作用：用 Python 代码编写桌面可视化程序。举个例子：不再依靠纯终端命令交互，而是做出带窗口、点击按钮就能触发功能的桌面软件。

下面先来搭建运行环境，再写几个实操示例，看完就能彻底理解。

---

树莓派安装PyQt的两种方式

树莓派上安装PyQt有两个渠道：

• APT系统软件源：安装稳定正式版；

• PIP：安装最新迭代版本。

方法 1：APT命令安装（推荐新手）

这是树莓派最适配、最稳妥的安装方式，适配所有基于Debian的Linux系统（树莓派OS全系通用）。

打开终端，输入命令：

sudo apt install python3-pyqt6

系统会自动下载安装 PyQt6，并补齐所有依赖组件，几秒即可完成。

补充：完整版树莓派系统通常预装了旧版 PyQt5，无需重复安装。

方法 2：PIP安装最新版PyQt

系统自带源里的版本会滞后几个迭代，想要最新功能就用pip安装。

个人日常项目优先选APT安装，系统更新时会自动同步升级，省心稳定；只有需要指定特定版本时，才选用 pip。

先安装pip必备依赖：

sudo apt install python3-pip python3-venv

搭建Python虚拟环境（规避externally-managed-environment环境报错）

python -m venv myprojectsource myproject/bin/activate

升级pip工具本身

pip install --upgrade pip

安装最新PyQt6

pip install pyqt6

如需沿用旧版PyQt5：

pip install PyQt5

开发调试Qt程序建议额外安装Qt开发头文件：

sudo apt install qt6-base-dev

树莓派PyQt上手实操

PyQt6 已经安装完毕，接下来正式编写代码。这套库语法相比普通Python库稍复杂，我会从极简代码入手，逐层添加功能，方便理解。

首个脚本

复制下方代码，生成最基础的桌面窗口：

from PyQt6.QtWidgets import QApplication, QMainWindowimport sysapp = QApplication([])win = QMainWindow()win.show()sys.exit(app.exec())

• PyQt6库体量庞大，遵循规范：只导入需要用到的类（本例：应用主程序类、主窗口类）；

• 初始化程序载体 + 空白主窗口；

• win.show() 调用窗口渲染并展示在屏幕上；

• sys.exit(app.exec())：开启程序循环监听，关闭窗口时彻底终止进程。

代码推荐用Thonny编辑器编写运行（树莓派自带，最适合新手调试），点击运行后，屏幕会弹出一个空白桌面窗口。

这是能运行的最小代码单元，没有任何文字、按钮控件。

给窗口添加基础控件

接下来逐步优化程序，实现这些效果：

• 自定义窗口标题、设置窗口尺寸

• 窗口内添加文字文本

• 添加可点击按钮，点击按钮触发事件

设置窗口标题与大小

QMainWindow自带内置方法修改窗口属性：

• setWindowTitle("窗口名称")：自定义顶部标题文字

• resize(宽度, 高度)：设定窗口长宽

你可以通过我们在第一个脚本中创建的「win」对象调用这些函数，调用写法如下：

win = QMainWindow()win.setWindowTitle("Your Title")win.resize(500,200)

我会在本文结尾给你一个完整的例子。我先介绍几个其他的。

窗口内添加文字

想要在窗口里展示文字，需要创建标签控件QLabel，类似PPT里的文本框：可以定义文字内容、调整大小、摆放位置。 

示例代码片段：

label = QLabel("This is my dumb text", win)label.adjustSize()label.move(20, 0)

必须在代码开头导入QLabel类，否则运行报错。

我们使用构造函数来定义初始文本以及它附加到哪个窗口。接下来，我们告诉标签调整自身大小以适应文本。最后，move函数将文本放在一个特定的位置。

添加可点击按钮

按钮是 GUI 程序最常用控件，核心要点：需要绑定点击事件，点击按钮自动执行指定函数。

代码片段：

button = QPushButton("Click here", win)button.move(20,40)button.clicked.connect(clickMethod)

需导入QPushButton类，并且提前定义被调用的函数。

和之前的思路一样，我们用QPushButton来定义它，并在上面设置文字。

然后，移动功能会将按钮放在您想要的任何位置。

整合窗口、文字、按钮全套功能代码：

from PyQt6.QtWidgets import QApplication, QMainWindow, QLabel, QPushButtonimport sysdef clickMethod():    print("Button clicked!")app = QApplication([])win = QMainWindow()win.setWindowTitle("Your Title")win.resize(500,200)label = QLabel("This is my text", win)label.adjustSize()label.move(100, 0)button = QPushButton("Click here", win)button.move(100,40)button.clicked.connect(clickMethod)win.show()sys.exit(app.exec())

运行效果：

窗口拥有自定义标题、一段提示文字、一个按钮；点击按钮，终端控制台就会打印提示文字。

你可以自行修改函数内部代码，实现自己需要的功能（比如操控 GPIO、读取文件、执行自动化任务等）。

PyQt深入学习方向

看完本篇入门教程，你已经掌握 PyQt 基础逻辑了。建议反复修改示例代码：调整窗口大小、增减文字和按钮、编写不同点击事件，巩固知识点。

进阶学习可查阅官方权威文档：

Qt for Python 官方文档：

https://doc.qt.io/qtforpython-6/

PyQt 教程维基：

https://wiki.python.org/moin/PyQt/Tutorials

官方文档内容全面，但对新手偏晦涩，最稳妥的方式：以本文示例代码为基础，一点点叠加新控件、新功能。

温馨提醒：如果你刚接触 Python，不建议直接上手 GUI 开发，先学好基础语法再来学习会轻松很多。推荐前期入门项目：

15个Python趣味树莓派小项目：

https://raspberrytips.com/python-projects-on-raspberry-pi/

Python操控树莓派摄像头实战：

https://raspberrytips.com/picamera2-raspberry-pi/

树莓派用Python编写我的世界小游戏：

https://raspberrytips.com/program-minecraft-raspberry-pi/

如果你想查阅原文，可以点击文章尾部的【阅读全文】。

一起学习、讨论更多的树莓派知识？扫码加入树莓派交流群！

Tip：对于刚接触树莓派的新手来说，面对英文文档、零散教程和复杂配置，很容易无从下手。pidoc.cn（ https://pidoc.cn/ ）就是为解决这些痛点而生的树莓派中文一站式学习平台，界面清晰、内容系统、更新及时，堪称新手入门的“保姆级” 网站，让零基础用户也能轻松上手树莓派。

---

OpenClaw 迷你树莓派 AI 主机！

ED-CLAWBOX 是一款基于树莓派CM5 的工业级 AI 智能体盒子，精致，高效，安全，专为 OpenClaw 端侧私有化部署而设计。

https://edatec.cn/zh/clawbox

---

树莓派CM0正式发布！

低成本，低功耗，紧凑型邮票孔封装计算模块，用极低的价格，享受整个树莓派生态和社区！

https://edatec.cn/zh/cm0