QtPy

What it is and what it does

QtPy is a thin abstraction layer that lets you write Qt applications using a single, unified API that works with any of the four major Qt Python bindings: PyQt5, PySide2, PyQt6, or PySide6. Instead of importing directly from a specific binding, you import from qtpy, and the library transparently routes your calls to whichever binding is installed and selected via the QT_API environment variable (defaulting to PyQt5 if multiple are present).

The main value is in reducing friction when porting code between bindings or upgrading Qt versions. When you need to switch from PyQt5 to PyQt6, or migrate from PyQt to PySide, you can do so module by module without rewriting your entire codebase. QtPy handles known incompatibilities—such as exposing PyQt's pyqtSignal, pyqtSlot, and pyqtProperty as Signal, Slot, and Property, and handling PyQt6's unscoped enums—so your code stays portable across all four bindings.

Use it for:

• Develop a desktop application that can run on either PyQt5 or PySide6 without code duplication.
• Gradually migrate an existing PyQt5 codebase to PyQt6 by updating imports to use QtPy first.
• Support multiple Qt bindings in a library so users can choose their preferred binding.
• Write tests that run against multiple Qt bindings to ensure compatibility.
• Simplify CI/CD by testing a single codebase against PyQt5, PySide2, PyQt6, and PySide6.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

QtPy provides a unified API for writing Qt applications that work across PyQt5, PySide2, PyQt6, and PySide6 without code changes.

Yes, if you are building or maintaining a Qt application and want flexibility in which binding you use or plan to migrate between bindings. The low install friction and active maintenance make it a safe dependency. Not necessary if you are locked into a single binding and have no plans to switch.

Install

qtpy on PyPI

pip install qtpy

uv add qtpy

poetry add qtpy

Installing QtPy

Before you install

Low friction install with a single runtime dependency (packaging). Active maintenance with recent releases and a stable codebase.

License in practice

MIT license is permissive; you can use QtPy in commercial and proprietary projects with minimal restrictions.

Quickstart

pip install qtpy

import qtpy

# Select binding via QT_API environment variable (pyqt5, pyside2, pyqt6, pyside6)
# QtPy routes calls to the selected binding transparently

Requires PyQt5, PySide2, PyQt6, or PySide6 to be installed separately; QtPy is only the abstraction layer.

Verify before relying

• Whether the package handles all edge cases between Qt5 and Qt6 enum differences automatically.
• Performance overhead of the abstraction layer compared to direct binding use.
• Completeness of compatibility wrappers for less common Qt modules and classes.

Package facts

Evidence: QtPy-2.4.3-py3-none-any.whl

Keywords: qt, PyQt5, PyQt6, PySide2, PySide6

Tags

More Libraries packages