Linux Mint下PySide6启动报错：xcb平台插件无法加载

核心原因 #

PySide6的Qt依赖库与系统xcb相关组件不匹配，或缺少必要的依赖包（PyQt5因系统适配性更好未出现此问题）。

具体解决步骤 #

1. 安装完整的xcb依赖库 #

仅安装xcb包不足以满足Qt插件需求，执行以下命令安装所有必要的xcb相关依赖：

sudo apt update && sudo apt install libxcb-xinerama0 libxcb-cursor0 libxcb-randr0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 libxcb-xkb1

2. 切换为系统包管理器安装的PySide6 #

如果之前用pip安装的PySide6存在兼容性问题，尝试用系统自带的包管理器安装：

sudo apt install python3-pyside6

系统版本的PySide6会自动适配系统的Qt依赖，大概率解决插件加载问题。

3. 调试插件加载细节（定位具体缺失依赖） #

设置Qt调试环境变量，启动应用查看详细报错日志，明确是哪个依赖缺失：

export QT_DEBUG_PLUGINS=1
python3 your_app.py

日志中会提示具体的缺失库，针对性安装即可。

4. 正确设置PySide6插件路径（针对pip安装版本） #

若必须使用pip安装的PySide6，自动获取并设置正确的平台插件路径：

export QT_QPA_PLATFORM_PLUGIN_PATH=$(python3 -c "import PySide6; print(PySide6.__path__[0] + '/plugins/platforms')")
python3 your_app.py

避免手动指定错误路径导致的加载失败。

5. 强制使用X11平台（针对Wayland会话） #

如果当前系统使用Wayland会话（Linux Mint 21+默认可能启用），强制用X11启动应用：

QT_QPA_PLATFORM=xcb python3 your_app.py

或在登录界面选择"Linux Mint Xorg"会话后再启动应用。

内容的提问来源于stack exchange，提问作者MasterShifu