Install & Compatibility
Where this runs
tested against v5.15.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.7s · import 0.000s · 220MB
218MB installed
● package 218MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QApplication
✓ from PyQt5.QtWidgets import QApplication
QWidget
✓ from PyQt5.QtWidgets import QWidget
QLabel
✓ from PyQt5.QtWidgets import QLabel
QPushButton
✓ from PyQt5.QtWidgets import QPushButton
QVBoxLayout
✓ from PyQt5.QtWidgets import QVBoxLayout
Qt
✓ from PyQt5.QtCore import Qt
✗ from PyQt5.QtGui import Qt
Qt core enums (like alignment flags, key codes) are typically found in QtCore.Qt, not QtGui.
This quickstart creates a simple PyQt5 window displaying 'Hello, PyQt5!' in a centrally aligned label. It demonstrates the basic structure of a PyQt5 application, including creating an QApplication instance, defining a main window (subclassing QWidget), adding a QLabel, setting layout, and starting the application's event loop.
import sys
from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QVBoxLayout
from PyQt5.QtCore import Qt
class MyWindow(QWidget):
def __init__(self):
super().__init__()
self.setWindowTitle('PyQt5 Hello World')
self.setGeometry(100, 100, 400, 200) # x, y, width, height
layout = QVBoxLayout()
self.label = QLabel('Hello, PyQt5!', self)
self.label.setAlignment(Qt.AlignCenter)
self.label.setStyleSheet("font-size: 24px; color: blue;")
layout.addWidget(self.label)
self.setLayout(layout)
if __name__ == '__main__':
app = QApplication(sys.argv)
window = MyWindow()
window.show()
sys.exit(app.exec_())
Debug
Known issues
breakingThe `exec()` method on QApplication and QDialog instances was renamed to `exec_()` in PyQt5 (and earlier versions targeting Python 2) to avoid conflicts with Python's `exec` keyword. While `exec()` works in PyQt5 for Python 3, `exec_()` is the widely adopted and safer convention for PyQt5 applications. In PyQt6, it reverted to `exec()`.fixAlways use `app.exec_()` for QApplication and dialogs in PyQt5 to ensure compatibility across various minor versions and to distinguish it from Python's keyword.
affects: All PyQt5 versions (for Python 3), especially when migrating from older code or considering PyQt6.
gotchaDevelopment tools like Qt Designer (`designer.exe`), `pyuic5`, and `pyrcc5` are no longer included directly with the `PyQt5` wheel installation. They are provided in a separate package, `pyqt5-tools`.fixInstall `pyqt5-tools` separately: `pip install pyqt5-tools~=5.15`. You can then find `designer.exe` (or equivalent) in your virtual environment's `Scripts` (Windows) or `bin` (Linux/macOS) directory.
affects: PyQt5 5.15.x and later, where these tools are separated.
breakingMigration from PyQt4 to PyQt5 involves significant breaking changes, notably the removal of the 'old-style' `QObject.connect()` signal/slot syntax and the re-organization of classes from the `QtGui` module into `QtGui`, `QtWidgets`, and `QtPrintSupport` modules.fixUpdate signal/slot connections to the 'new-style' Python callable syntax (e.g., `button.clicked.connect(self.my_slot)`). Adjust imports to reflect the new module structure for GUI elements.
affects: All PyQt5 versions when porting from PyQt4.
gotchaWith the release of PyQt6 (targeting Qt6), PyQt5 is considered a mature but older generation. While PyQt5 is still actively maintained, new projects are often encouraged to start with PyQt6 for modern features, better performance, and long-term support. There are differences in enum naming (fully qualified names in PyQt6), module organization (e.g., `QAction` moved), and High DPI scaling defaults.fixFor new projects, evaluate PyQt6. If sticking with PyQt5, be aware of migration paths and potential differences if examples/tutorials from PyQt6 are encountered. PyQt5 supports fully qualified enum names which helps with future compatibility.
affects: All PyQt5 users, particularly those starting new projects or considering future upgrades.
gotchaOfficial PyQt5 documentation often links to the C++ Qt documentation. This means users may need to infer Python equivalents from C++ signatures and concepts, which can be a learning curve for those unfamiliar with C++.fixFamiliarize yourself with common C++ to Python binding patterns (e.g., `const QString&` in C++ often translates to `str` in Python). Utilize community tutorials and examples specific to PyQt5.
affects: All PyQt5 versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'PyQt5'
PyQt5 is not installed in the active Python environment.
ModuleNotFoundError: No module named 'PyQt5.QtWebEngineWidgets'
The QtWebEngineWidgets module, containing QWebEngineView, is an optional component that needs separate installation.
fixpip install PyQt5WebEngine
NameError: name 'QApplication' is not defined
The QApplication class, essential for initializing any PyQt5 application, has not been imported.
fixfrom PyQt5.QtWidgets import QApplication
TypeError: 'NoneType' object is not callable
This often happens when connecting signals to slots if a method call (e.g., `self.my_method()`) is used instead of a method reference (`self.my_method`), passing the method's return value (often None) to `connect`.
fixEnsure you pass the method reference without parentheses: `button.clicked.connect(self.my_method)`
QPixmap: Cannot load image
The image file specified for QPixmap could not be found at the given path, the path is incorrect, or the image file is corrupted or unsupported.
fixVerify that the image file exists at the specified absolute or relative path and that the path is correct.
Upgrade
Version history
5.15.11latest on PyPI · released Jul 19, 2024
Audit
Dependencies
qt5-baserequiredPyQt5 is a binding for the C++ Qt5 toolkit, which is the underlying GUI framework. While pip handles binary distribution for common OSes, the core Qt5 libraries are fundamental.
pyqt5-toolsoptionalProvides development tools like Qt Designer, which are not included in the main PyQt5 wheel package.
python-pyqt5-siprequiredSIP is a tool that generates the Python bindings for C++ libraries. It is a fundamental component for PyQt5's operation, often bundled implicitly with wheel installations but explicit for source builds or certain Linux distributions.