Ubuntu21.10运行OpenCV代码提示找不到Qt wayland平台插件怎么解决

问题本质 #

该报错由pip预编译的opencv-python包自带裁剪版Qt运行库导致：预编译包裁剪了Wayland平台插件，和Ubuntu系统、Python版本、Qt4兼容性均无关联。

解决方法 #

方案1：临时指定X11后端（推荐，零成本生效） #

无需修改任何依赖或文件，仅需强制Qt使用X11平台渲染，两种实现方式：

• 单次运行脚本时添加环境变量前缀：
  QT_QPA_PLATFORM=xcb python3 你的脚本文件名.py
• 直接在代码头部添加环境变量声明，导入cv2前执行即可：

import os
os.environ["QT_QPA_PLATFORM"] = "xcb"
# 后续原有代码无需修改
import cv2
img = cv2.imread("path")
cv2.imshow("window", img)
cv2.waitKey()

方案2：手动补充Wayland插件 #

如果需要保留Wayland渲染，可手动把系统Qt的Wayland插件复制到报错路径：

1. 先安装系统QtWayland依赖：
   sudo apt install qtwayland5
2. 把系统插件目录下的Wayland相关文件复制到cv2的Qt插件路径：

# 先确认目标路径的platforms文件夹存在，不存在则新建
mkdir -p /home/peepo/.local/lib/python3.9/site-packages/cv2/qt/plugins/platforms
# 复制所有Wayland插件到目标路径
sudo cp /usr/lib/x86_64-linux-gnu/qt5/plugins/platforms/libqwayland-* /home/peepo/.local/lib/python3.9/site-packages/cv2/qt/plugins/platforms/

方案3：更换opencv安装源（一劳永逸） #

pip预编译的opencv-python裁剪了大量组件，容易出现平台兼容问题，换成系统源的opencv包会直接调用系统完整Qt环境，从根源避免插件缺失问题：

1. 先卸载现有pip安装的opencv包：
   pip uninstall opencv-python opencv-python-headless
2. 安装系统源的Python opencv包：
   sudo apt install python3-opencv

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