PyQt6/PySide6 Bindings for (the amazing) Qlementine
Modern QStyle for desktop Qt6 applications... ready for Python!
pip install PyQt6-Qlementine
# or
pip install PySide6-Qlementine# 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.
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).
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.
Contributions are welcome! See CONTRIBUTING.md for dev tips.