JetsonNV 上解决 PyQt5 “Could not load the Qt platform plugin ‘xcb‘“ 错误

March 6, 2025·chase

本文目录展开章节导航

先看第一条错误，而不是最后一句提示

Jetson 上的 PyQt5 启动错误常见两类：

qt.qpa.xcb: could not connect to display
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" ... even though it was found.

第一类优先检查显示连接与授权；第二类还可能是插件依赖或 Qt 版本混用。最后一句“重新安装可能修复”是通用提示，不是诊断结论。

1. 确认运行环境

uname -m
printf 'DISPLAY=%s\nWAYLAND_DISPLAY=%s\n' "$DISPLAY" "$WAYLAND_DISPLAY"
python -c "import sys; from PyQt5.QtCore import QT_VERSION_STR, PYQT_VERSION_STR; print(sys.executable, QT_VERSION_STR, PYQT_VERSION_STR)"
QT_DEBUG_PLUGINS=1 python example.py

Jetson 的系统镜像、JetPack、ARM64 架构和 Qt 包来源要一起记录。不要将桌面 x86_64 环境的插件目录复制过来。

2. 根据场景选择显示方式

场景	应检查的条件
Jetson 本机桌面	在已登录桌面的终端运行，检查真实 DISPLAY 与会话权限
SSH 图形转发	客户端有 X server，服务端允许转发，使用 `ssh -X user@jetson`
远程桌面	在远程桌面会话内部启动程序，使用该会话的显示变量
无窗口图片输出	评估 `offscreen` 或不依赖 Qt 的渲染后端

export DISPLAY=:0 只设置一个地址，不会创建 X server 或授予访问权限。不要使用 xhost + 关闭所有访问控制。若确需跨用户访问，应由显示会话拥有者按最小权限授权，并在完成后撤销。

SSH 转发不保证所有 OpenGL/EGL 应用都可用；遇到硬件加速需求，应单独验证渲染后端。

3. 插件存在但无法加载

从 QT_DEBUG_PLUGINS 输出找到实际的 libqxcb.so，再对这个可信文件运行 ldd。只针对报告的缺失库安装对应架构的软件包，避免盲目安装一串桌面依赖。

同时检查 QT_PLUGIN_PATH、QT_QPA_PLATFORM_PLUGIN_PATH 是否指向另一套 Qt。qt5-default 的包名不是跨 Ubuntu 版本通用的修复方案，系统 Qt 与 pip/Conda Qt 也不应混用插件。

4. 最小窗口验证

将以下内容保存为 example.py，先排除业务代码和机器人通信线程的影响：

import sys
from PyQt5 import QtWidgets

app = QtWidgets.QApplication(sys.argv)
window = QtWidgets.QWidget()
window.setWindowTitle("PyQt5 on Jetson")
window.resize(320, 120)
window.show()
sys.exit(app.exec_())

本机桌面执行 python example.py，确认窗口可显示和关闭。无窗口任务可试：

QT_QPA_PLATFORM=offscreen python example.py

这个窗口示例在 offscreen 模式下仍会进入事件循环，且没有可见窗口，需主动结束；它不是图片导出程序。offscreen 也不保证 Qt Quick 或 OpenGL 上下文可用。

参考：Qt 插件部署与诊断。

阅读自测与验收

在 Jetson 上核对进程架构与 Qt 平台插件依赖，避免混入 x86_64 库；路径存在不代表二进制架构正确。
分别确认显示会话授权和平台后端，远程 SSH 设置 DISPLAY 不能替代授权；无窗口任务才考虑适合的离屏方式。

Last updated on September 5, 2026