---
id: qtpy
version: "2.4.3"
license: MIT
license_treatment: permissive
maintenance: active
---

# QtPy — Provides an abstraction layer on top of the various Qt bindings (PyQt5/6 and PySide2/6).

License: permissive · Maintenance: active · Downloads: 4.4M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 4.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

qt abstraction layer, pyqt pyside compatibility, cross-qt binding wrapper, unified qt api, qt5 qt6 compatibility, pyqt6 pyside6 adapter, qt binding abstraction, qt-abstraction, cross-platform-ui, binding-compatibility

[View on SkillFed](https://skillfed.io/packages/qtpy) · [View on PyPI](https://pypi.org/project/qtpy/)