在 Raspberry Pi OS 安装 PyQt5：APT、虚拟环境与 GUI 测试

普通 Raspberry Pi OS 项目应优先安装发行版预编译的 python3-pyqt5。这样 Python、Qt、平台插件和树莓派架构由同一软件源匹配，也避免在板子上进行昂贵的源码编译。文末完整保留 2019 年旧命令，但 qt5-default 和当时列出的 Qt4 软件包已经不是现行安装路线。

Table of Contents

当前路线速览

sudo apt update
sudo apt install python3-pyqt5
python3 -c "from PyQt5.QtCore import PYQT_VERSION_STR, QT_VERSION_STR; print('PyQt', PYQT_VERSION_STR, 'Qt', QT_VERSION_STR)"

这条路线适用于 Raspberry Pi OS Desktop 或兼容的 Debian 系镜像。Raspberry Pi OS Lite 可以通过导入测试，但真正显示窗口仍需要显示服务器；无桌面环境时应明确采用离屏测试。

1. 修改系统前先确认环境

cat /etc/os-release
dpkg --print-architecture
python3 --version
apt-cache policy python3-pyqt5

只有当 apt-cache policy 显示来自本系统已配置仓库的候选版本时，才继续安装。不要为了让包名出现，就粘贴属于另一 Debian 或 Raspberry Pi OS 版本的软件源。Raspberry Pi 对跨大版本升级的建议是写入新镜像，而不是直接替换源中的发行版名称。

2. 安装运行时绑定

sudo apt update
sudo apt install python3-pyqt5

Debian 的基础包包含常用的 QtCore、QtGui、QtWidgets、QtNetwork、QtPrintSupport、QtTest 和 QtXml 绑定。图表、多媒体、WebEngine、SVG、串口或 Qt Quick 等功能可能使用独立软件包。先查看当前系统实际提供什么：

apt search '^python3-pyqt5.'

只安装应用确实导入的模块。不同系统版本的软件包名和可用范围可能不同。

3. 验证解释器与绑定来源

command -v python3
python3 -c "import PyQt5; print(PyQt5.__path__)"
python3 -c "from PyQt5.QtCore import PYQT_VERSION_STR, QT_VERSION_STR; print('PyQt', PYQT_VERSION_STR, 'Qt', QT_VERSION_STR)"
apt-cache policy python3-pyqt5

这四项分别回答：正在运行哪个解释器、它从哪里找到 PyQt5、实际载入了什么 PyQt/Qt 版本、系统副本由哪个 APT 候选包提供。求助时应保留完整输出。

4. 测试一个真实控件

把下面内容保存为 pyqt5_smoke.py：

import sys

from PyQt5.QtCore import PYQT_VERSION_STR, QT_VERSION_STR, QTimer
from PyQt5.QtWidgets import QApplication, QLabel

app = QApplication(sys.argv)
label = QLabel(f"PyQt {PYQT_VERSION_STR} / Qt {QT_VERSION_STR}")
label.resize(320, 80)
label.show()
QTimer.singleShot(750, app.quit)
raise SystemExit(app.exec_())

在 Raspberry Pi 桌面终端中运行：

python3 pyqt5_smoke.py

程序应短暂显示一个小窗口，然后自动退出。CI 或纯命令行环境可明确要求 Qt 使用离屏平台：

QT_QPA_PLATFORM=offscreen python3 pyqt5_smoke.py

离屏测试通过只说明 Qt 能初始化，并不能证明真实 Wayland 或 X 桌面路径正常。

在虚拟环境中使用 APT 安装的 PyQt5

Raspberry Pi OS 把系统 Python 标记为外部管理。不要用 sudo pip 或 --break-system-packages 绕过边界。若项目既要复用 APT 版 PyQt5，又要隔离纯 Python 依赖，可创建能读取系统软件包的虚拟环境：

sudo apt install python3-venv
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
python -c "from PyQt5.QtCore import PYQT_VERSION_STR; print(PYQT_VERSION_STR)"

请在项目 README 记录这一选择。普通虚拟环境若没有 --system-site-packages，本来就看不到 /usr/lib/python3/dist-packages；此时的 ModuleNotFoundError 不代表 APT 安装失败。

只在需要时添加开发工具

运行普通应用不需要旧的 qt5-default 元包或 C++ 头文件。需要 Qt Designer，以及 PyQt 的 UI、资源和翻译工具时，先确认候选版本，再安装现行软件包：

apt-cache policy pyqt5-dev-tools qttools5-dev-tools
sudo apt install pyqt5-dev-tools qttools5-dev-tools
command -v pyuic5 pyrcc5 pylupdate5 designer

pyqt5-dev-tools 提供 pyuic5、pyrcc5、pylupdate5 等工具；qttools5-dev-tools 提供包括 Designer 在内的 Qt 应用。只有真正编译扩展或 Qt 程序时才安装 pyqt5-dev、qtbase5-dev，普通 Python GUI 不需要它们。

何时才应使用 PyPI

Riverbank 也通过 PyPI 发布 PyQt5。仅当项目确实需要不同于系统包的版本时采用这条路线，并始终放在虚拟环境内：

sudo apt install python3-venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install PyQt5

等待之前先看 pip 选择了什么：wheel 是预编译包，.tar.gz 则表示树莓派将从源码构建，需要相应依赖、时间、内存和兼容的 Qt 工具链。若这并非有意安排，应停止并改用 APT。不要混用 sudo pip、系统 Python 和 APT 管理的文件。

按症状排查

症状	检查	安全的下一步
`Unable to locate package python3-pyqt5`	`cat /etc/os-release`、`apt-cache policy python3-pyqt5` 与软件源配置	修正为该系统版本的官方源；不要添加无关镜像或随机下载 `.deb`
`externally-managed-environment`	pip 是否正写入系统 Python	改用 APT，或激活虚拟环境；不要全局关闭保护
虚拟环境内出现 `ModuleNotFoundError: PyQt5`	`python -c 'import sys; print(sys.executable); print(*sys.path, sep="n")'`	用 `--system-site-packages` 重建，或在该 venv 内安装选定的 PyPI 版本
Qt 无法连接显示器	`printf 'DISPLAY=%snWAYLAND_DISPLAY=%sn' "$DISPLAY" "$WAYLAND_DISPLAY"`	从真实桌面会话运行，明确配置远程显示，或只在测试时使用 `QT_QPA_PLATFORM=offscreen`
`Could not load the Qt platform plugin`	用 `QT_DEBUG_PLUGINS=1` 重跑一次并保存第一条缺失库信息	安装匹配的仓库包或修复环境；不要从别的机器复制插件目录，也不要盲目修改权限
pip 编译时出现 `Killed`	确认 pip 是否选了源码包，并查看可用内存	优先使用预编译 APT 包，或把计划内的源码构建转移到合适的构建机

更新、卸载或迁移

随当前系统版本的其余软件一起更新 PyQt5：

sudo apt update
sudo apt full-upgrade

应用不再需要它时卸载运行时包：

sudo apt remove python3-pyqt5

接受任何 autoremove 前都要审查 APT 将删除的内容。仍绑定 PyQt4 的应用，只应短暂冻结旧环境以完成迁移：Riverbank 已明确 PyQt4 不受支持，并可能无法在当前系统构建或运行。应迁移到受支持的 Python 3 与 Qt 绑定，而不是削弱当前 Raspberry Pi OS。

2019 年原始笔记（逐字保留）

以下两个命令块与原始导出完全一致。它们只作为历史记录，不是现行安装说明。

sudo apt-get update
sudo apt-get install qt5-default pyqt5-dev pyqt5-dev-tools

For PyQt4

sudo apt-get install qt4-default qt4-designer qt4-doc qt4-dev-tools python-qt4