Qtプラットフォームプラグイン「xcb」の読み込み失敗

問題の概要

Ubuntuや他のLinuxディストリビューションでQtアプリケーションを実行する際、以下のエラーが発生することがあります：

qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.

Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, xcb.

このエラーは、X Window System用のQtプラットフォームプラグイン（xcb）が見つかっているにもかかわらず、必要な依存ライブラリが不足しているため正常に読み込めないことを示しています。

根本原因

デバッグ情報（QT_DEBUG_PLUGINS=1を設定した場合）を確認すると、以下のような詳細なエラーが表示されます：

Cannot load library /path/to/libqxcb.so: (libQt6XcbQpa.so.6: cannot open shared object file: No such file or directory)

lddコマンドで依存関係を確認すると、libQt6XcbQpa.so.6ファイルが見つからないことが確認できます。

解決方法

方法1: 必要なライブラリのインストール（推奨）

最も一般的な解決策は、不足しているXCB関連のライブラリをインストールすることです：

Ubuntu/Debian

sudo apt install libxcb-xinerama0 libxcb-xkb1 libxcb1 libxcb-glx0 \
libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 \
libxcb-cursor0 libxcb-util-dev

CentOS/RHEL/Fedora

sudo yum install xcb-util*
# または
sudo dnf install xcb-util*

conda環境

conda install xcb-util xcb-util-cursor xcb-util-image \
xcb-util-keysyms xcb-util-renderutil xcb-util-wm

Qt6専用の解決策

Qt 6.5.0以降では、libxcb-cursor0が特に必要です：

sudo apt install libxcb-cursor0

方法2: 開発ライブラリのインストール

アプリケーションをビルドする場合、開発ライブラリもインストールする必要があります：

sudo apt install '^libxcb.*-dev' libx11-xcb-dev libglu1-mesa-dev \
libxrender-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev

方法3: Qtライブラリの確認と修正

アプリケーションのデプロイ時にlibQt6XcbQpa.so.6が正しくコピーされているか確認してください：

1. アプリケーションのlibディレクトリにlibQt6XcbQpa.so.6が存在するか確認
2. 実行ファイルのRUNPATHを確認：

   readelf -d <実行ファイル名> | grep -E 'RUNPATH|RPATH'

3. 必要ならば、CMakeのqt_generate_deploy_scriptを使用して適切なデプロイを設定

方法4: 環境変数の設定

Wayland環境を使用している場合や、ヘッドレス実行が必要な場合：

Wayland環境

export QT_QPA_PLATFORM=wayland

オフスクリーンレンダリング

export QT_QPA_PLATFORM=offscreen

ディスプレイ設定

export DISPLAY=:0

注意

環境変数による解決は一時的な対策であり、根本的なライブラリ不足を解決するものではありません。

方法5: Python環境での解決策

Python環境（特にPyQt/PySideやOpenCV使用時）では以下の対策が有効です：

OpenCVの再インストール

pip uninstall opencv-python opencv-contrib-python opencv-python-headless
pip install opencv-python-headless

PyQt5/6の調整

# Qt6と互換性の問題がある場合
pip uninstall PyQt5
sudo apt install qt6-base-dev
pip install PyQt6

トラブルシューティングの手順

1. デバッグ情報の取得：

   export QT_DEBUG_PLUGINS=1
   ./your_application

2. 依存関係の確認：

   ldd /path/to/libqxcb.so

3. プラグインパスの確認：

   ls /path/to/qt/plugins/platforms/

まとめ

Qtの「xcbプラグイン読み込み失敗」エラーは、主に以下の原因で発生します：

• XCB関連ライブラリの不足
• 適切なQtライブラリのデプロイ失敗
• 環境変数の不適切な設定
• Python環境でのパッケージ競合

ほとんどの場合、方法1で紹介したライブラリのインストールで解決します。環境に応じて適切な解決策を選択してください。