How to switch from PyQt5 to PySide6 with QtPy?

Set the QT_API environment variable to 'pyside6' before launching your app. QtPy will redirect imports automatically, allowing the same code to run without changes, as per the environment configuration details.

QtPy or direct PyQt6 for a new project?

Use direct PyQt6 if you're certain about sticking with one binding and don't need cross-compatibility. QtPy is better for projects expecting future binding switches or requiring multi-binding support, as it abstracts differences.

Does QtPy work with QtQuick or QML?

QtPy supports core Qt modules following the Qt5 layout, but some advanced modules like QtQuick may require careful testing. The compat module focuses on helpers for QFileDialog and SIP/Shiboken, not all Qt features.

How to set up MyPy type checking with QtPy?

Run 'qtpy mypy-args' to generate CLI arguments (e.g., --always-true=PYQT5) and inject them into your MyPy command. This ensures type definitions align with the selected binding, as described in the type checker integration section.

What if multiple Qt bindings are installed?

QtPy defaults to PyQt5 unless QT_API is set. You can control this via the environment variable to specify the binding, preventing ambiguity in multi-binding environments.

Can I use QtPy with conda?

Yes, QtPy is available on conda-forge, and the README shows it's tested with conda installations across different bindings and Python versions. Ensure the desired binding is installed in the same conda environment.

Open-Awesome

qtpy

MITPythonv2.4.3

A Python abstraction layer for writing Qt applications that work with PyQt5, PySide2, PyQt6, and PySide6 using a single codebase.

GitHub

1.1k stars161 forks0 contributors

What is qtpy?

QtPy is a Python abstraction layer that provides a uniform API for developing Qt applications, compatible with PyQt5, PySide2, PyQt6, and PySide6. It solves the problem of maintaining separate codebases when targeting different Qt bindings or migrating between Qt versions, allowing developers to write once and run across multiple Qt implementations.

Target Audience

Python developers building desktop GUI applications with Qt who need to support multiple Qt bindings (PyQt/PySide) or migrate between Qt5 and Qt6 without extensive code changes.

Value Proposition

Developers choose QtPy because it dramatically reduces the complexity and maintenance burden of supporting multiple Qt backends, enabling incremental upgrades and ensuring long-term compatibility with a minimal, dependency-free abstraction layer.

Overview

Provides an uniform layer to support PyQt5, PySide2, PyQt6, PySide6 with a single codebase

Use Cases

Best For

Writing Qt applications that must run on both PyQt and PySide without code duplication
Migrating existing PyQt5/PySide2 codebases to PyQt6/PySide6 incrementally
Developing libraries or frameworks that need to be compatible with multiple Qt bindings
Maintaining projects where team members prefer different Qt bindings
Ensuring long-term compatibility as Qt versions evolve
Simplifying CI/CD pipelines by testing against multiple Qt bindings with the same codebase

Not Ideal For

Projects committed to a single Qt binding with no future cross-compatibility needs
Applications requiring direct access to PyQt's SIP or PySide's Shiboken APIs for low-level C++ integration
Performance-critical real-time GUIs where abstraction layer overhead must be minimized
Teams that prefer binding-specific tooling or IDE integrations not supported by QtPy's unified API

Pros & Cons

Pros

Unified API Across Bindings

Enables writing code once for PyQt5, PySide2, PyQt6, and PySide6 by importing from qtpy, eliminating duplicate codebases as highlighted in the Key Features.

Incremental Migration Support

Facilitates gradual porting between Qt versions or bindings without full rewrites, with QtPy handling incompatibilities internally per the README's seamless transition feature.

Runtime Binding Flexibility

Allows binding selection via the QT_API environment variable (e.g., set to 'pyside6'), with PyQt5 as a default fallback for easy deployment configuration.

Type Checker Integration

Provides CLI tools (qtpy mypy-args, qtpy pyright-config) to generate configurations for MyPy and Pyright/Pylance, ensuring static analysis works with dynamic binding selection.

Cons

No Binding Installation

QtPy doesn't install any Qt binding itself; users must manually install PyQt or PySide, adding setup steps and potential version dependency conflicts.

Limited Advanced Feature Coverage

Abstraction may not fully encapsulate all binding-specific features or newer Qt modules, requiring fallback to direct imports for edge cases, as hinted by the compat module's focused wrappers.

Configuration Overhead

Type checker integration requires running CLI commands or editing config files (e.g., pyrightconfig.json), which adds complexity compared to native binding setups.

Frequently Asked Questions

Related Projects

pencil

The Pencil Project's unique mission is to build a free and opensource tool for making diagrams and GUI prototyping that everyone can use.

Stars9,747

Forks787

Last commit22 days ago

elements

Elements C++ GUI library

Stars3,679

Forks278

Last commit5 months ago

cage

A Wayland kiosk

Stars1,883

Forks118

Last commit13 hours ago

chilipie

Easy-to-use Raspberry Pi image for booting directly into full-screen Chrome, with built-in convenience features for unattended operation. Perfect for dashboards and build monitors.

Stars1,398

Forks155

Last commit4 years ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub