Install & Compatibility
Where this runs
tested against v2.4.3 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.000s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QtWidgets
✓ from qtpy import QtWidgets
✗ from qtpy import QtWidgets
This quickstart demonstrates a basic QtPy application. It initializes a QApplication, creates a QWidget with a QLabel and QPushButton, sets up a simple layout, and connects a slot to the button's click signal. It highlights how to import modules from `qtpy` and also shows an optional environment variable `QT_API` that can be set to force a specific backend if multiple are installed.
import sys
import os
from qtpy import QtWidgets, QtCore
# Optional: force a specific Qt API (e.g., 'PyQt5', 'PyQt6', 'PySide2', 'PySide6')
# os.environ['QT_API'] = 'PyQt5'
# Create the application object
app = QtWidgets.QApplication(sys.argv)
# Create a simple widget
widget = QtWidgets.QWidget()
widget.setWindowTitle('Hello QtPy!')
widget.setGeometry(300, 300, 300, 150)
layout = QtWidgets.QVBoxLayout()
label = QtWidgets.QLabel('Welcome to QtPy!')
button = QtWidgets.QPushButton('Click Me')
layout.addWidget(label)
layout.addWidget(button)
widget.setLayout(layout)
def on_button_click():
label.setText('Button clicked from ' + os.environ.get('QT_API', 'auto-detected') + '!')
button.clicked.connect(on_button_click)
# Show the widget
widget.show()
# Start the event loop
sys.exit(app.exec_())
Debug
Known issues
gotchaQtPy does not install Qt bindings. You must explicitly install at least one binding (e.g., `PyQt5`, `PyQt6`, `PySide2`, or `PySide6`) for QtPy to function. If no binding is found, `QtBindingsNotFoundError` will be raised.fixInstall your preferred Qt binding: `pip install PyQt6` or `pip install PySide6` etc. You can also install with QtPy extras: `pip install qtpy[pyqt6]`.
affects: All versions
breakingWhen migrating to Qt6 bindings (PyQt6/PySide6), be aware of significant changes in the underlying Qt framework. Modules or classes may have been moved (`QtGui.QScreen` to `QtWidgets.QScreen`) or removed (e.g., `QtWebEngineCore` vs `QtWebEngineWidgets` module structure, `QLibraryInfo.LibraryLocation` renamed to `LibraryPath`). While QtPy attempts to abstract these, some code adjustments might still be necessary.fixConsult Qt documentation for Qt6 migration guides. Review `qtpy`'s changelog for specific compatibility fixes. Be mindful of module paths and class availability.
affects: QtPy versions supporting Qt6 (>=2.0.0)
gotchaIf multiple Qt bindings are installed, QtPy follows a specific detection order (usually PyQt6, PySide6, PyQt5, PySide2). To force a specific binding, set the `QT_API` environment variable (e.g., `QT_API='PySide6'`).fixBefore importing `qtpy`, set `os.environ['QT_API'] = 'PySide6'` in your Python code or define the environment variable in your shell.
affects: All versions
deprecatedWhen using PySide6, `QSqlDatabase.exec()` raises a `DeprecationWarning` in Qt 6.5+. QtPy 2.4.3 and later ignore this warning by default to reduce noise, but the underlying API usage is still deprecated in PySide6.fixBe aware of the deprecation if you use `QSqlDatabase.exec()` directly. Consider updating your code to use newer, non-deprecated database interaction methods if available in PySide6.
affects: QtPy >=2.4.3 (fix applied), PySide6 users
gotchaPrior to QtPy 2.4.3, `isinstance` checks for `QMenu` and `QToolBar` (especially when dealing with wrapped objects or specific inheritance hierarchies) could fail unexpectedly, leading to runtime errors or incorrect behavior.fixUpgrade to QtPy 2.4.3 or newer. If upgrading is not immediately possible, carefully review `isinstance` checks involving these classes.
affects: <2.4.3
Upgrade
Version history
2.4.3latest on PyPI · released Feb 11, 2025
Audit
Dependencies
PyQt5optionalOne of the underlying Qt bindings is required by QtPy.
PyQt6optionalOne of the underlying Qt bindings is required by QtPy.
PySide2optionalOne of the underlying Qt bindings is required by QtPy.
PySide6optionalOne of the underlying Qt bindings is required by QtPy.