PySide6-Qlementine 1.4.3.0rc3

PySide6 bindings for Qlementine, a modern QStyle for desktop Qt6 applications

PyQt6/PySide6-Qlementine

PyQt6/PySide6 Bindings for (the amazing) Qlementine

Modern QStyle for desktop Qt6 applications... ready for Python!

Installation

pip install PyQt6-Qlementine
# or 
pip install PySide6-Qlementine

Usage

# or PySide6 & PySide6Qlementine
from PyQt6.QtWidgets import QApplication
from PyQt6.QtCore import QJsonDocument
from PyQt6Qlementine import QlementineStyle, Theme

app = QApplication([])

# Apply Qlementine as the application style
# (this alone will apply the default Qlementine theme, which is lovely)
style = QlementineStyle(app)
app.setStyle(style)

# Define a custom theme, for all keys, see:
# https://oclero.github.io/qlementine/theme/#full-example
theme_dict = {
    "meta": {"name": "Custom", "author": "Your Name", "version": "1.0"},
    "primaryColor": "#ff00ff",
    "backgroundColorMain1": "#1a1a2e",
    "backgroundColorMain2": "#1a1a2e",
}

theme = Theme.fromJsonDoc(QJsonDocument.fromVariant(theme_dict))
style.setTheme(theme)

See C++ documentation for more information.

See also examples in this repo.

The autogenerated type stubs are also useful for understanding the API.

Why QStyle over QSS?

If you're coming from the Python Qt ecosystem, you're likely used to theming via Qt Style Sheets (QSS) — every major Python theming library (QDarkStyleSheet, qt-material, BreezeStyleSheets, etc.) relies on them.

QSS is easy to author, but it comes with serious trade-offs: it breaks setPalette() and setFont(), ignores system dark/light mode changes, forces you to restyle all sub-controls when you customize one, and adds measurable startup and reparenting cost from CSS parsing.

A proper parametrized QStyle implementation (like Qlementine) avoids all of this — colors, spacing, animations, border-radii, and pixel metrics are computed natively in C++ with full QPainter access, zero parsing overhead, and complete respect for QPalette. The reason Python libraries haven't taken this approach is that subclassing QProxyStyle in Python incurs a C++/Python boundary crossing on every paint call, making it unperformant for anything beyond icon overrides.

Qlementine sidesteps that entirely: the style is implemented in C++ and simply exposed to Python (through these bindings), giving you the correctness and performance of a native QStyle implementation with the ease of use of a Python library (and parametrized geometry, colors, animations, and fonts through Qlementine's Theme API).

License

The code in this repository is licensed under the MIT License.

The packaged/distributed bindings are:

• GPL-3.0-only for PyQt6-Qlementine (required by PyQt6's license)
• MIT for PySide6-Qlementine

See the LICENSE file in each package for more details.

Developers & Contributing

Contributions are welcome! See CONTRIBUTING.md for dev tips.