# BreezeStyleSheets: Breeze-like Qt themes you can generate and extend

> BreezeStyleSheets is a set of light and dark Qt stylesheets in the style of Breeze and BreezeDark, generated from theme files and extensible through an extension system, and it can be built for PyQt5, PyQt6, PySide2 and PySide6 or compiled straight into a CMake build. It ships one tagged release, 0.0.1, and is still labelled beta.

**Alexhuszagh/BreezeStyleSheets** — Breeze/BreezeDark-like Qt StyleSheets 

- Repository: https://github.com/Alexhuszagh/BreezeStyleSheets
- Stars: 664 · Forks: 135
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/alexhuszagh-breezestylesheets

## Generated stylesheets instead of a hand-maintained .qss file

BreezeStyleSheets provides light and dark stylesheets for Qt applications in the visual style of Breeze and BreezeDark, the KDE theme family. The README describes them as rendering consistently across platforms, including high DPI screens, and says the stylesheets are tested with most Qt widgets and widget properties so the result looks the same on different operating systems, desktop environments and Qt versions.

The important structural detail is that these are not static files you copy and edit. Each stylesheet is generated from a theme file and can be extended through an extension system, which the README presents as the way to build custom stylesheets for your own application. That is the part worth understanding before you adopt it. A single hand-written .qss file is easy to start with and painful to maintain once it covers every widget state across two colour schemes. Here the theme file is the source, the generator produces the output, and your changes go into extensions rather than into the generated result.

The repository layout shows the pieces: a breezestylesheets directory holds the Python package, resources holds the pre-built themes, extensions holds the extension sources, scripts holds helper tooling, and configure.py sits at the root as the build entry point. There is also a testsuite under test, an example directory with both C++ and Python projects, and supporting files such as ISSUES.md, a Test Coverage.md document and a coverage.svg.

So this is a stylesheet generator plus a theme, not a widget library and not a runtime dependency. The pyproject.toml declares no runtime dependencies at all, and the package is built with hatchling.

## configure.py takes styles, extensions and a target framework

The build is driven by a single Python script. The README shows how to build all pre-packaged themes, including the PyQt5 and PyQt6 support, by looping over the frameworks you care about:

```bash
# choose only the frameworks you want
frameworks=("pyqt5" "pyqt6" "pyside2" "pyside6")
for framework in "${frameworks[@]}"; do
    python configure.py \
        --styles all \
        --extensions all \
        --qt-framework "${framework}" \
        --resource breeze.qrc \
        --compiled-resource "breeze_${framework}.py"
done
```

Each flag has a clear job. --styles selects which themes to build, --extensions selects which extensions to include, --qt-framework names the binding the output is compiled for, --resource points at the Qt resource collection, and --compiled-resource names the Python file that the Qt resource compiler will produce. The README notes that the --compiled-resource flag requires the correct RCC to be installed for the chosen framework, which is where most of the setup friction lives.

Outputs land in two places. All generated themes go into the dist subdirectory, and the compiled Python resources go into resources/breeze_{framework}.py, for example resources/breeze_pyqt5.py. By default the dark and light themes come pre-built in the resources directory, so the loop above is only necessary if you want the full set or a specific framework.

The optional dependencies in pyproject.toml show what the generator can read: pyyaml, tomli for Python versions before 3.11, and xml2dict. On Windows there is a detect extra that pulls in winrt-Windows.UI and winrt-Windows.UI.ViewManagement, which suggests the generator can inspect the native system theme when it is running there. That is a detail worth checking if you plan to generate on a Windows build agent.

## Loading the compiled resource into a PyQt application

Using the stylesheet from Python means importing the compiled resource module, reading the .qss out of it with QFile, and handing the text to the application. The README gives this example for BreezeDark:

```python
from PyQt5 import QtWidgets
from PyQt5.QtCore import QFile, QTextStream
# This must match the name of the file and be in the Python search path.
# To modify the search path, add the directory containing the file to `sys.path`.
import breeze_resources


def main():
    app = QtWidgets.QApplication(sys.argv)

    # set stylesheet
    file = QFile(":/dark/stylesheet.qss")
    file.open(QFile.ReadOnly | QFile.Text)
    stream = QTextStream(file)
    app.setStyleSheet(stream.readAll())

    # code goes here

    app.exec_()
```

Two details in that snippet deserve a second look before you paste it into your project. The example calls sys.argv but the import block only pulls in PyQt5, so a plain copy of it raises a NameError at the QApplication constructor unless you add an import sys yourself. The example also uses the PyQt5 form of the file open flags, QFile.ReadOnly and QFile.Text, where PyQt6 exposes the same flags as scoped enums, and it calls app.exec_(), which PyQt6 renamed to exec(). Both are trivial to fix, but they are the kind of detail that tells you the snippet was written against PyQt5 and lightly adapted.

The resource path is the Qt resource syntax, :/dark/stylesheet.qss, which only resolves because the stylesheet was compiled into the resource bundle. The compiled resource file itself is produced by the framework's own resource compiler, and the README lists them: pyrcc5 for PyQt5, pyside6-rcc for PySide6 and for PyQt6 as well, and pyside2-rcc for PySide2, with the note that PySide2 requires Python 3.10 or earlier. If you skip the compiled-resource step, you can still use the pre-compiled resources that already ship in the resources directory.

## A CMake path that builds the stylesheets inside your project

For a C++ Qt project, the README describes a CMake integration contributed by @ruilvo, with a full example under example/cpp/cmake. The build fetches the repository, runs the Python generator, and compiles the resource collection as part of the normal build. The setup starts with the standard Qt automagic options:

```cmake
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_AUTOUIC ON)
```

The generator itself is pulled in with FetchContent, pinned to the main branch of the repository:

```cmake
FetchContent_Declare(
  breeze_stylesheets
  GIT_REPOSITORY https://github.com/Alexhuszagh/BreezeStyleSheets.git
  GIT_TAG origin/main
  GIT_PROGRESS ON
  GIT_SHALLOW 1
  USES_TERMINAL_DOWNLOAD TRUE)
```

The README states that this requires CMake 3.14 or newer, and the find_package call for the Qt components includes Core, Gui, Widgets and Svg, all as required. The C++ side of the project also needs a Python interpreter, found through find_package, because the stylesheets are generated by Python rather than by CMake itself.

Two practical notes. The FetchContent block pins to origin/main, so your build tracks the development branch of the stylesheet project rather than a tagged release, and the shallow clone keeps the download small. If you want reproducible builds, you would pin a tag or a commit instead, and the tags you have to choose from are thin, since the repository has published a single release, 0.0.1, on 2024-09-09.

## A single release, a beta marker, and a busy repository

The project describes itself as configurable and gives a long feature list in the README, including an extension system, a customization section, a debugging section and a development guide with git hooks, linting, type checks and distribution files. What it does not have is a release history. The only tagged release is 0.0.1, named Initial Release, published on 2024-09-09. The last push was on 2026-10-05, so the code is being worked on, but that work has not produced a new tag.

The package metadata is honest about the maturity level. The pyproject.toml classifiers list the development status as 4 - Beta, and the version is dynamic rather than hard-coded. The Python requirement is 3.7.4 or newer, which is a wide range for a project whose tooling pins modern versions of pytest, ruff and mypy, so the floor is there for the generated output to run on older interpreters rather than for the generator itself.

There is a discrepancy worth flagging in the dependencies. The pyproject.toml declares dependencies = [] with everything optional, while the exported requirements.txt lists pydantic 2.11.9, annotated-types, pydantic-core and pydantic-extra-types, with the comment showing they come via breezestylesheets and pydantic-extra-types. So the installed package pulls in pydantic even though the declared dependency list is empty, which means an installation from PyPI may bring a runtime dependency the manifest does not advertise. If dependency hygiene matters to your build, check what actually gets installed rather than trusting the empty list.

The repository also carries a lot of governance and tooling scaffolding: AGENTS.md, CLAUDE.md, SECURITY.md, CODE_OF_CONDUCT.md, a LICENSES directory, a MaterialUi.LICENSE file, an .editorconfig and a uv.lock. The presence of a Claude configuration file next to the code suggests the project is developed with AI assistance, which is worth knowing when you read the generated stylesheets.

## Why a stylesheet is not the same as a platform theme

The clearest alternative is to use Breeze itself. Breeze ships with KDE Plasma and is available as a Qt platform theme, so an application that follows platform conventions picks up the Breeze look without a single line of QSS. The difference in approach is the one that matters. A platform theme changes how the whole application is drawn, including the parts Qt does not style through a stylesheet, and it follows the user's system settings, including the light and dark preference and the colour scheme. A stylesheet is an override layer: it repaints widgets you can name, in a fixed palette that you choose.

The consequence for a product is that a stylesheet cannot honour a user's dark mode preference by itself. If you ship one light stylesheet and one dark stylesheet and pick between them, you are maintaining a UI decision that the platform already makes for you, and you inherit the problem of the application looking out of place in an environment configured differently. The BreezeStyleSheets README does list a Known Issues and Workarounds section, which suggests the author has hit this class of problem, but that section is not reproduced in the documentation available here.

The second alternative is writing your own .qss. For a small application with a handful of widgets this is often the cheapest option, and you inherit no generator, no resource compiler and no build integration. BreezeStyleSheets earns its place when you want the Breeze look specifically, on more than one platform, and you would rather not keep the style rules in sync by hand. The price is the toolchain: a Python generator, per-framework resource compilers, and a stylesheet that overrides rather than cooperates with the platform.

The licensing side is settled. The project is MIT licensed, and the LICENSES directory plus the MaterialUi.LICENSE file indicate that the third party content bundled into the stylesheets carries its own terms that are kept separate from the project's own licence. If you ship the generated output inside a commercial application, that separation is the part to read.

## Conclusion

BreezeStyleSheets fits a Python or C++ Qt team that wants a Breeze look across platforms without writing the style rules by hand, and it fits a team whose application must inherit a real platform theme less well, since a stylesheet overrides widget drawing rather than the native palette. Before adopting it, run configure.py for the one framework you ship rather than all four, confirm the resource compiler for that framework is on your PATH, since the compiled-resource flag needs pyrcc5 or pyside6-rcc, and read the Known Issues and Workarounds section that the README lists but does not reproduce here.

## FAQ

### How do I build the BreezeStyleSheets themes?

Run python configure.py with --styles, --extensions, --qt-framework, --resource and --compiled-resource flags. The README shows a loop over pyqt5, pyqt6, pyside2 and pyside6, and generated themes end up in the dist subdirectory with compiled Python resources in resources/breeze_{framework}.py.

### Which resource compiler do I need for each Qt framework?

PyQt5 uses pyrcc5, PyQt6 and PySide6 use pyside6-rcc, and PySide2 uses pyside2-rcc and requires Python 3.10 or earlier. The compiled-resource flag needs the right one on your path.

### Can I use BreezeStyleSheets with a C++ Qt application?

Yes. The README describes a CMake integration that uses FetchContent to pull in the repository, runs the Python generator and compiles the resource collection, and it requires CMake 3.14 or newer. A full example is under example/cpp/cmake.

### Is BreezeStyleSheets published to PyPI?

The package is built with hatchling and the pyproject.toml names it breezestylesheets with a dynamic version, and the Documentation URL points at readthedocs. The only GitHub release is 0.0.1, published on 2024-09-09.

### What licence does BreezeStyleSheets use?

The project is MIT licensed, with the licence stored in LICENSE.md. A separate LICENSES directory and a MaterialUi.LICENSE file hold the terms for third party content bundled into the stylesheets.

## Sources

- [Alexhuszagh/BreezeStyleSheets on GitHub](https://github.com/Alexhuszagh/BreezeStyleSheets)
- [Issues](https://github.com/Alexhuszagh/BreezeStyleSheets/issues)
- [License: MIT](https://github.com/Alexhuszagh/BreezeStyleSheets/blob/main/LICENSE)
- [README](https://github.com/Alexhuszagh/BreezeStyleSheets/blob/main/README.md)
- [Releases](https://github.com/Alexhuszagh/BreezeStyleSheets/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alexhuszagh-breezestylesheets