Raspberry Pi OS に PyQt5 を導入する：APT、仮想環境、GUI テスト

通常の Raspberry Pi OS プロジェクトでは、ディストリビューションが事前ビルドした python3-pyqt5 を使うのが基本です。Python、Qt、プラットフォームプラグイン、Pi のアーキテクチャを同じリポジトリで整合させ、ボード上での重いソースビルドを避けられます。2019 年の旧コマンドは末尾に全文保存していますが、qt5-default と当時列挙された Qt4 パッケージは現行ルートではありません。

現行ルートの要約

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

Raspberry Pi OS Desktop、または互換性のある Debian 系イメージで使う手順です。Raspberry Pi OS Lite でもインポートは可能ですが、ウィンドウ表示にはディスプレイサーバーが必要です。デスクトップのない環境では、意図を明示したオフスクリーンテストを使います。

1. 変更前にシステムを特定する

cat /etc/os-release
dpkg --print-architecture
python3 --version
apt-cache policy python3-pyqt5

apt-cache policy に、この OS 用として設定済みのリポジトリから候補が表示された場合だけ先へ進みます。パッケージ名を出すために、別の Debian／Raspberry Pi OS リリース向けリポジトリを貼り付けてはいけません。Raspberry Pi は、大きな OS バージョンをまたぐ場合にリリース名をそのまま置換するのではなく、新しいイメージから始めるよう案内しています。

2. ランタイムバインディングを入れる

sudo apt update
sudo apt install python3-pyqt5

Debian の基本パッケージには、よく使う QtCore、QtGui、QtWidgets、QtNetwork、QtPrintSupport、QtTest、QtXml バインディングが含まれます。Charts、Multimedia、WebEngine、SVG、Serial Port、Qt Quick などは別パッケージの場合があります。この OS が実際に提供する追加モジュールを先に調べます。

apt search '^python3-pyqt5.'

アプリが本当に import するモジュールだけを追加してください。名前と提供範囲は OS リリースによって異なり得ます。

3. インタープリターとバインディングを検証する

command -v python3
python3 -c "import PyQt5; print(PyQt5.__path__)"
python3 -c "from PyQt5.QtCore import PYQT_VERSION_STR, QT_VERSION_STR; print('PyQt', PYQT_VERSION_STR, 'Qt', QT_VERSION_STR)"
apt-cache policy python3-pyqt5

順に、どの Python を実行しているか、PyQt5 をどこで見つけたか、実際に読み込んだ PyQt／Qt の版、システムコピーを提供する APT 候補を確認できます。質問するときは出力全体を残します。

4. 実際のウィジェットを試す

次を pyqt5_smoke.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()
QTimer.singleShot(750, app.quit)
raise SystemExit(app.exec_())

Raspberry Pi のデスクトップ端末で実行します。

python3 pyqt5_smoke.py

小さなウィンドウが短時間表示され、プロセスが終了すれば成功です。CI やコマンドライン専用環境では、Qt にオフスクリーンプラットフォームを明示します。

QT_QPA_PLATFORM=offscreen python3 pyqt5_smoke.py

オフスクリーンで通るのは Qt の初期化を確認しただけであり、実際の Wayland／X デスクトップ経路までは保証しません。

APT 版 PyQt5 を仮想環境で使う

Raspberry Pi OS のシステム Python は外部管理です。sudo pip や --break-system-packages で境界を破らないでください。APT 版 PyQt5 を再利用しつつ、純 Python 依存を分離するプロジェクトでは、システムパッケージを参照できる仮想環境を作ります。

sudo apt install python3-venv
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
python -c "from PyQt5.QtCore import PYQT_VERSION_STR; print(PYQT_VERSION_STR)"

この選択はプロジェクト README に記録します。--system-site-packages のない通常の venv が /usr/lib/python3/dist-packages を見ないのは設計どおりです。その中の ModuleNotFoundError は APT の失敗を意味しません。

開発ツールは必要なときだけ加える

通常のアプリ実行に、旧 qt5-default メタパッケージや C++ ヘッダーは不要です。Qt Designer と PyQt の UI・リソース・翻訳ツールが必要なら、候補を確認して現行パッケージを入れます。

apt-cache policy pyqt5-dev-tools qttools5-dev-tools
sudo apt install pyqt5-dev-tools qttools5-dev-tools
command -v pyuic5 pyrcc5 pylupdate5 designer

pyqt5-dev-tools は pyuic5、pyrcc5、pylupdate5 などを、qttools5-dev-tools は Designer を含む Qt アプリを提供します。pyqt5-dev や qtbase5-dev は、開発ファイルを必要とするビルド時だけ使い、普通の Python GUI のためには入れません。

PyPI を選ぶべき場合

Riverbank は PyPI でも PyQt5 を公開しています。OS パッケージと異なる版が本当に必要な場合だけ、仮想環境内で使います。

sudo apt install python3-venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install PyQt5

待つ前に pip の選択を読みます。wheel はビルド済みですが、.tar.gz は Pi 上でのソースビルドを意味し、ビルド依存、時間、RAM、互換 Qt ツールチェーンが必要です。意図していなければ中止して APT を使います。sudo pip、システム Python、APT 管理ファイルを混在させてはいけません。

症状別トラブルシューティング

症状確認安全な次の手
Unable to locate package python3-pyqt5cat /etc/os-release、apt-cache policy python3-pyqt5、ソフトウェアソースその OS リリース用のソースを直す。無関係なミラーやランダムな .deb は使わない
externally-managed-environmentpip がシステム Python を対象にしていないかAPT を使うか venv を有効化する。保護を全体で無効にしない
venv 内の ModuleNotFoundError: PyQt5python -c 'import sys; print(sys.executable); print(*sys.path, sep="n")'--system-site-packages 付きで作り直すか、その venv 内に選んだ PyPI 版を入れる
Qt がディスプレイへ接続できないprintf 'DISPLAY=%snWAYLAND_DISPLAY=%sn' "$DISPLAY" "$WAYLAND_DISPLAY"実デスクトップから実行し、リモート表示を意図的に構成する。テストだけなら QT_QPA_PLATFORM=offscreen を使う
Could not load the Qt platform plugin一度だけ QT_DEBUG_PLUGINS=1 で再実行し、最初の不足ライブラリ行を保存対応するリポジトリパッケージか環境を直す。別マシンのプラグインをコピーしたり権限を盲目的に変えたりしない
pip ビルド中に Killedソースアーカイブが選ばれたか、空きメモリはあるかビルド済み APT パッケージを優先するか、計画したビルドを適切なマシンへ移す

更新・削除・移行

現在の OS リリース内で、PyQt5 を他のパッケージと一緒に更新します。

sudo apt update
sudo apt full-upgrade

不要になったランタイムを削除します。

sudo apt remove python3-pyqt5

autoremove の提案は、承認前に削除対象を確認してください。PyQt4 に依存するアプリは、移植に必要な間だけ旧環境を固定します。Riverbank は PyQt4 を未サポートとし、現行システムではビルドも実行もできない可能性があると明記しています。現在の Raspberry Pi OS を弱めるのではなく、サポート中の Python 3 と Qt バインディングへ移行します。

2019 年の原文（逐語保存）

以下の二つのコマンドブロックは原エクスポートどおりです。歴史資料であり、現行手順ではありません。

sudo apt-get update
sudo apt-get install qt5-default pyqt5-dev pyqt5-dev-tools

For PyQt4

sudo apt-get install qt4-default qt4-designer qt4-doc qt4-dev-tools python-qt4

確認した公式資料

Leave a Reply