QtPy

Warnings

• gotcha QtPy 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.
  Fix: Install your preferred Qt binding: `pip install PyQt6` or `pip install PySide6` etc. You can also install with QtPy extras: `pip install qtpy[pyqt6]`.
• breaking When 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.
  Fix: Consult Qt documentation for Qt6 migration guides. Review `qtpy`'s changelog for specific compatibility fixes. Be mindful of module paths and class availability.
• gotcha If 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'`).
  Fix: Before importing `qtpy`, set `os.environ['QT_API'] = 'PySide6'` in your Python code or define the environment variable in your shell.
• deprecated When 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.
  Fix: Be 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.
• gotcha Prior 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.
  Fix: Upgrade to QtPy 2.4.3 or newer. If upgrading is not immediately possible, carefully review `isinstance` checks involving these classes.

Install

• pip install qtpy Install QtPy (requires a Qt binding)
• pip install qtpy[pyqt5] # or [pyqt6], [pyside2], [pyside6] Install QtPy with a specific backend (example for PyQt5)

Imports

• QtWidgets

  from qtpy import QtWidgets

  QtPy abstracts the specific binding. Import directly from `qtpy` to ensure cross-binding compatibility.
• QtCore

  from qtpy import QtCore

  Import `QtCore` for fundamental non-GUI classes.
• QtGui

  from qtpy import QtGui

  Import `QtGui` for GUI components not specific to widgets.

Quickstart

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_())