Install PyQt5 on Raspberry Pi OS: APT, Virtual Environments, and GUI Tests

For a normal Raspberry Pi OS project, install the distribution’s precompiled python3-pyqt5 package. It keeps Python, Qt, the platform plugins, and the Pi’s architecture aligned, and avoids an expensive source build. The old 2019 commands are preserved at the end of this page, but qt5-default and the listed Qt4 packages are not the current route.

Table of Contents

Current route at a glance

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

Use this route on Raspberry Pi OS Desktop or another compatible Debian-based image. On Raspberry Pi OS Lite, importing PyQt can work, but showing a window requires a display server or an intentional offscreen test.

1. Identify the system before changing it

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

Continue when apt-cache policy shows a candidate from the repositories configured for this OS. Do not paste a repository intended for another Debian or Raspberry Pi OS release merely to make the package name appear. Raspberry Pi recommends a fresh image for major OS upgrades rather than changing release names in place.

2. Install the runtime binding

sudo apt update
sudo apt install python3-pyqt5

This base Debian package includes the commonly used QtCore, QtGui, QtWidgets, QtNetwork, QtPrintSupport, QtTest, and QtXml bindings. Features such as charts, multimedia, WebEngine, SVG, serial ports, or Qt Quick may use separate packages. Discover what this specific OS offers before installing an add-on:

apt search '^python3-pyqt5\.'

Install only the module the application actually imports. Package names and availability can differ by OS release.

3. Verify the interpreter and binding

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

These checks answer four different questions: which interpreter is running, where it sees PyQt5, which PyQt/Qt versions it loaded, and which APT package supplied the system copy. Keep the complete output when asking for help.

4. Test an actual widget

Save this as 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_())

From a Raspberry Pi desktop terminal, run:

python3 pyqt5_smoke.py

A small window should appear briefly and the process should exit. For a CI or command-line-only smoke test, ask Qt to use its offscreen platform explicitly:

QT_QPA_PLATFORM=offscreen python3 pyqt5_smoke.py

An offscreen pass proves that the application can initialize Qt; it does not prove that the real Wayland or X desktop path works.

Use an APT-installed PyQt5 package inside a virtual environment

Raspberry Pi OS treats its system Python as externally managed. Do not solve that boundary with sudo pip or --break-system-packages. If the project should use the APT copy of PyQt5 plus isolated pure-Python dependencies, create a virtual environment that can see system packages:

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

Record this choice in the project README. A regular virtual environment without --system-site-packages intentionally cannot see /usr/lib/python3/dist-packages, so ModuleNotFoundError there does not mean the APT installation failed.

Add developer tools only when needed

The runtime application does not need the old qt5-default meta-package or C++ headers. For Qt Designer and PyQt’s UI/resource/translation tools, first check the candidates, then install the current packages:

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 provides tools such as pyuic5, pyrcc5, and pylupdate5; qttools5-dev-tools provides Qt applications including Designer. Install pyqt5-dev or qtbase5-dev only when a build genuinely needs development files, not for an ordinary Python GUI.

When a PyPI installation is justified

Riverbank also publishes PyQt5 through PyPI. Use that route only when a project requires a version different from the OS package, and keep it inside a virtual environment:

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

Read pip’s selection before waiting for the build. A downloaded wheel is prebuilt; a .tar.gz means the Pi will compile from source, which needs build dependencies, time, RAM, and a compatible Qt toolchain. If that was not intentional, stop and use the APT route. Never mix sudo pip, system Python, and APT-owned files.

Troubleshooting by symptom

Symptom	Check	Safe next action
`Unable to locate package python3-pyqt5`	`cat /etc/os-release`; `apt-cache policy python3-pyqt5`; configured software sources	Correct the repositories for that exact OS release; do not add an unrelated mirror or download a random `.deb`
`externally-managed-environment`	Whether pip is targeting system Python	Use APT, or activate a virtual environment; do not bypass the protection globally
`ModuleNotFoundError: PyQt5` in a venv	`python -c 'import sys; print(sys.executable); print(*sys.path, sep="\n")'`	Recreate it with `--system-site-packages`, or install the chosen PyPI build inside that venv
Qt cannot connect to a display	`printf 'DISPLAY=%s\nWAYLAND_DISPLAY=%s\n' "$DISPLAY" "$WAYLAND_DISPLAY"`	Run from a real desktop session, configure remote display forwarding intentionally, or use `QT_QPA_PLATFORM=offscreen` only for tests
`Could not load the Qt platform plugin`	Rerun once with `QT_DEBUG_PLUGINS=1`; save the first missing-library line	Install the matching repository package or repair the environment; do not copy plugin trees from another machine or change their permissions blindly
`Killed` while pip builds PyQt5	Check whether pip selected a source archive and inspect available memory	Prefer the precompiled APT package, or move a planned source build to a suitable build machine

Upgrade, remove, or migrate

Update PyQt5 with the rest of the current OS release:

sudo apt update
sudo apt full-upgrade

Remove the runtime package when the application no longer needs it:

sudo apt remove python3-pyqt5

Review APT’s proposed changes before accepting any autoremove. For an application still tied to PyQt4, freeze the old environment only long enough to port it: Riverbank labels PyQt4 unsupported and warns that it may not build or run on current systems. Port to a supported Python 3 and Qt binding rather than weakening a current Raspberry Pi OS installation.

Original 2019 note (verbatim)

The two command blocks below are preserved exactly as published in the original export. They are historical context, not current installation instructions.

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