UbuntuでPyQt5を実行する

2026年メンテナンス注記：ページ末尾の日付付きアーカイブに、xcbエラー、個人的な修復記録、画像参照を含む2019年の完全な本文を、行末空白だけ正規化して保存しています。旧文にはUbuntuリリース、Python/PyQt/Qtバージョン、不足ライブラリ、インストールしたパッケージがありません。そのため万能な修復策の根拠にはできません。以下のメンテナンス版では、パッケージを変更する前に、実際のインタープリター、Qtインストール、表示セッション、ローダーの正確な失敗を診断します。

インストール経路を一つ選ぶ

PyQt5はUbuntuパッケージまたはRiverbankのPyPI wheelから導入できます。どちらも有効ですが、インストール時と実行時のインタープリターを一致させる必要があります。python --version、インストールコマンド、解決されたPyQt/Qtバージョンを記録してください。

UbuntuパッケージとシステムPython

Ubuntuはサポート対象リリースのUniverseコンポーネントでpython3-pyqt5を公開しています。

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)'

この経路ではUbuntuがパッケージ化したPythonとQtを使います。APTがパッケージを見つけられない場合は、インストール済みUbuntuリリース向けの正しいリポジトリが有効か確認してください。別リリース用のリポジトリをコピーして追加してはいけません。

プロジェクト仮想環境とRiverbank wheel

プロジェクトを分離した環境にする場合：

sudo apt update
sudo apt install python3-venv
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install PyQt5
python -c 'from PyQt5.QtCore import PYQT_VERSION_STR, QT_VERSION_STR; print("PyQt", PYQT_VERSION_STR, "Qt", QT_VERSION_STR)'

Riverbankによると、PyQt5 wheelは対応するQtライブラリもインストールします。ただし表示サーバーやプラットフォームプラグインのランタイムライブラリなど、OS側の機能には依存します。環境を有効にしている間はそのpythonを使い、別のインタープリターでインストールしたものを起動しないでください。システムのパッケージ管理境界を越えるsudo pipは避けます。

最小でテスト可能なアプリを実行する

次をhello_pyqt5.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()

if "--smoke-test" in sys.argv:
    QTimer.singleShot(0, app.quit)

raise SystemExit(app.exec_())

Python構文を確認してから、通常のUbuntuデスクトップ端末で起動します。

python3 -m py_compile hello_pyqt5.py
python3 hello_pyqt5.py

仮想環境内ではpython3をpythonに置き換えます。PyQtとQtのバージョンを表示するウィンドウが見えることが、デスクトップでの期待結果です。--smoke-testは後述する自動表示テスト専用です。

xcbエラーが示すこと、示さないこと

歴史的なエラーは次のものでした。

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.

2019年のQt xcbプラットフォームプラグインエラー

この画像は過去のエラー種別を示す資料であり、特定のUbuntuパッケージが不足していた証拠ではありません。

QtはQPAプラットフォームプラグインを使い、GUIコードをウィンドウシステムへ接続します。X11ではxcbがそのプラグインです。「found」は候補プラグインファイルを発見したことしか意味しません。共有ライブラリの不足、プラグインとQtライブラリの不整合、プラグインパスの上書き、利用可能な表示の欠如でも、読み込みまたは初期化は失敗します。

最初から無関係なlibxcbパッケージをまとめて入れないでください。まずどの境界で失敗しているかを確定します。

1. インタープリターとQtツリーを確認する

失敗するものと同じインタープリターで診断します。

command -v python3
python3 --version
python3 - <<'PY'
import PyQt5
from PyQt5.QtCore import PYQT_VERSION_STR, QT_VERSION_STR, QLibraryInfo

print("PyQt package:", PyQt5.__file__)
print("PyQt version:", PYQT_VERSION_STR)
print("Qt version:", QT_VERSION_STR)
print("Qt plugins:", QLibraryInfo.location(QLibraryInfo.PluginsPath))
PY

仮想環境では全行でpythonを使います。PyQt5.__file__とプラグインディレクトリが予期しないインストールを指す場合、Qtツリー間でファイルをコピーせず、インタープリターまたは環境を修正します。

Qtは、グローバルなQT_PLUGIN_PATHが別のQtインストールに干渉し得ると警告しています。上書き設定を確認します。

env | grep -E '^QT_(PLUGIN_PATH|QPA_PLATFORM_PLUGIN_PATH|QPA_PLATFORM)=' || true

診断として、2つのプラグインパス上書きを外して再試行します。

env -u QT_PLUGIN_PATH -u QT_QPA_PLATFORM_PLUGIN_PATH python3 hello_pyqt5.py

これで動くなら、別の固定プラグインパスへ置き換えるのではなく、環境設定から古い上書きを除去します。

2. 表示が存在するか確認する

アクセス制御を変更せずにセッションを確認します。

printf 'DISPLAY=%snWAYLAND_DISPLAY=%snXDG_SESSION_TYPE=%sn' 
  "${DISPLAY-}" "${WAYLAND_DISPLAY-}" "${XDG_SESSION_TYPE-}"

通常のローカルUbuntuデスクトップは利用可能な表示接続を提供します。単純なSSHシェル、コンテナ、サービス、CIジョブでは、どちらの表示変数も使えない場合があります。XCBライブラリを追加しても、表示サーバーや認証は作成されません。

xhost +を近道にしてはいけません。Xサーバーのアクセス制御を弱めます。正しく認証されたデスクトップ/リモート表示セッション、または後述する隔離済みヘッドレステストを使います。

3. プラグインが失敗した理由をQtに出力させる

Qtは詳細なプラグイン読み込み診断用にQT_DEBUG_PLUGINSを文書化しています。

QT_DEBUG_PLUGINS=1 python3 hello_pyqt5.py 2>qt-plugin-debug.log

最後の一般的なエラーだけでなく、libqxcb.so付近で最初に出るローダーエラーを調べます。

grep -E 'libqxcb|not found|cannot open|undefined symbol|version' qt-plugin-debug.log

ログにはローカルパスや環境情報が含まれる場合があります。非公開で保管し、共有前に削除またはマスキングしてください。

4. インストール済みxcbプラグインの依存を確認する

同じインタープリターでプラットフォームプラグインディレクトリを出力します。

qt_plugin_dir="$(python3 -c 'from PyQt5.QtCore import QLibraryInfo; print(QLibraryInfo.location(QLibraryInfo.PluginsPath))')"
find "$qt_plugin_dir/platforms" -maxdepth 1 -name 'libqxcb.so' -print

Ubuntuまたは選択した仮想環境が入れた信頼できるプラグインについて、未解決ライブラリを調べます。

ldd "$qt_plugin_dir/platforms/libqxcb.so" | grep 'not found' || true

不足がなければ、それ以上XCBパッケージをインストールしません。デバッグログに戻り、互換性のないシンボル/バージョン、意図しないプラグインツリー、表示接続エラーを探します。

特定の共有オブジェクトが不足している場合、その正確なファイル名を現在のUbuntuリリース向けパッケージへ対応付けます。

sudo apt update
sudo apt install apt-file
sudo apt-file update
apt-file search libxcb-xinerama.so.0

たとえば、診断がlibxcb-xinerama.so.0の不足を示し、現在のリリースのパッケージ索引がlibxcb-xinerama0へ対応付けた場合だけ、そのパッケージを入れます。パッケージ名と依存はリリースやアーキテクチャで変わり得ます。根拠のあるパッケージを入れた後、ldd、スモークテスト、実アプリを再実行します。

5. デスクトップ、offscreen、仮想Xテストを分ける

それぞれ異なる問いに答えるテストです。

Qtのoffscreenスモークテストはxcbを使わずにウィジェットを構築します。

QT_QPA_PLATFORM=offscreen python3 hello_pyqt5.py --smoke-test

成功すれば、PythonがPyQt5をimportし、利用可能なoffscreenプラグインで例を構築できることは示せます。しかしxcbやデスクトップ表示の動作は証明しません。

ヘッドレスCIでX11/xcb経路を試すには、隔離された仮想Xサーバーを使います。

sudo apt update
sudo apt install xvfb xauth
xvfb-run -a python3 hello_pyqt5.py --smoke-test

xvfb-runはX認証データを作り、Xvfbを起動し、コマンドを実行して終了後にクリーンアップします。Xvfbが成功してデスクトップ起動が失敗するなら、実デスクトップのセッション、認証、環境を調べます。offscreenが成功してXvfbが失敗するなら、xcbとX11依存を重点的に調べます。

WaylandデスクトップでQT_QPA_PLATFORM=xcbをグローバルに強制しないでください。利用可能なプラットフォームはインストールされたQtビルドとセッションに依存します。自動選択で動くなら変更せず、記録した診断コマンドでのみ一時的に上書きします。

6. 失敗の特徴を読んでから対応を選ぶ

証拠可能性の高い境界次の対応
ModuleNotFoundError: No module named 'PyQt5'インタープリターが違う、またはそこにPyQt5がない意図したAPT/仮想環境経路を選び、そのインタープリターで確認する
libNAME.so... => not foundまたは“cannot open shared object file”ランタイムライブラリ不足正確なファイル名をapt-file searchし、現リリースで対応するパッケージを入れて再診断する
“undefined symbol”、非互換Qtバージョン、意外なプラグインパスQt/プラグインツリーの混在古いパス上書きを除き、一貫したインストールを再構築する。libqxcb.soを手動コピーしない
“could not connect to display”または空/無効な表示変数セッション/表示境界ログイン済みデスクトップ、設定済みリモート表示、offscreen、Xvfbを目的に応じて使う
offscreen成功、Xvfb失敗X11/xcbの読み込み・初期化QT_DEBUG_PLUGINSとlddの結果を調べる
Xvfb成功、デスクトップ失敗デスクトップセッション、認証、環境2つのセッションの表示変数とQt上書きを比較する
最小テストは全て成功、実アプリだけ失敗アプリ固有のimport、プラグイン、描画、起動コード段階的にアプリを縮小し、最初に増えたエラーを記録する

7. 原因を隠す修正を避ける

  • libxcbで始まる全パッケージを入れず、欠落ファイルで裏付けられたものだけを入れる。
  • システムQt、wheel同梱Qt、Conda、IDE、別アプリの間でプラットフォームプラグインをコピーしない。
  • チュートリアルからコピーしたパスをQT_PLUGIN_PATH、QT_QPA_PLATFORM_PLUGIN_PATH、LD_LIBRARY_PATHへグローバル設定しない。
  • 他ユーザーの表示やパッケージに到達するため、アプリをsudoで実行しない。
  • UbuntuのPython環境をsudo pipで変更しない。
  • QT_QPA_PLATFORM=offscreenを対話型デスクトップアプリの修正だと考えない。意図的に可視ウィンドウを出さない方法である。
  • ローカルパスと環境情報を確認する前に、プラグインデバッグログを公開しない。

再現可能な検証記録

次の結果をIssueまたはプロジェクトと一緒に保存します。

  • lsb_release -dsとdpkg --print-architectureによるUbuntuリリース・アーキテクチャ
  • 正確なPython実行ファイルとバージョン
  • PyQt/QtバージョンとPyQt5.__file__
  • インストール経路と、該当する場合はロックしたプロジェクト依存
  • セッション秘密を共有せずに記録したDISPLAY、WAYLAND_DISPLAY、XDG_SESSION_TYPEの有無
  • Qtプラグインディレクトリと、最初に関係するQT_DEBUG_PLUGINSローダーエラー
  • 未解決のldd項目と利用したUbuntuパッケージ対応
  • 構文、offscreen、Xvfb、実デスクトップのテスト結果
  • 実施した変更とロールバック方法

この記録により、再現可能な修正と「XCB関連の何かを入れたら動いた」を区別できます。

---

2019年の原エクスポート（出典アーカイブ）

アーカイブ境界：以下のコードブロック内はout/posts/2019-04-23-run-pyqt5-in-ubuntu-1898/index.mdにあるpost 1898の完全な本文で、エクスポート内容の日付は2019年4月23日です。言葉遣い、句読点、曲線引用符、画像パス、個人的な主張は変更せず、行末空白だけ正規化しています。現在の修復手順として実行しないでください。


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.

I accidentally installed the xcb plugin and the problem solved.

![](images/image-1.png)

---

一次資料・公式資料

Leave a Reply