# PyQt-Fluent-Widgets: Fluent Design Widgets for PyQt5, PySide6 and PyQt6

> A GPLv3 widget library that brings Windows 11 Fluent styling to Qt applications in Python, with separate branches per binding and a paid Pro tier. Here is how it installs, what it does well, and where the licence and the packaging get in the way.

**zhiyiYo/PyQt-Fluent-Widgets** — A fluent design widgets library based on C++ Qt/PyQt/PySide. Make Qt Great Again.

- Repository: https://github.com/zhiyiYo/PyQt-Fluent-Widgets
- Website: https://qfluentwidgets.com
- Stars: 8,113 · Forks: 775
- Language: Python
- License: GPL-3.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/zhiyiyo-pyqt-fluent-widgets

## What PyQt-Fluent-Widgets actually replaces

Qt ships with a widget set that looks like Qt. If you want an application that resembles Windows 11, the usual route is stylesheets, custom paintEvent overrides, and a pile of per-widget tweaks that break the moment a Qt version changes. PyQt-Fluent-Widgets takes the other route: it reimplements the controls themselves in Python on top of Qt, so a navigation view, a settings card or an info bar is a class you instantiate rather than a stylesheet you maintain.

The README describes it as "a fluent design widgets library based on PyQt5", and the repository topics list PyQt5, PyQt6, PySide2 and PySide6 alongside winui and winui3. The intended audience is Python desktop developers who have already chosen Qt and now need the visual layer. It is not a cross-toolkit abstraction and it is not a web technology wrapper. The reference points named in the README are Microsoft's Windows design guidelines and the WinUI Gallery, so the target is a native-feeling Windows application that still runs on Linux and macOS, which the platform badge lists as Win32, Linux and macOS.

## How the library is structured across PyQt5, PyQt6 and PySide6

The mechanism is straightforward: Python classes that subclass Qt widgets and draw themselves. The default branch targets PyQt5, and the README points readers using PySide2, PySide6 or PyQt6 to separate branches named PySide2, PySide6 and PyQt6. That is the central architectural decision and the central inconvenience. There is no runtime binding detection in the package you get from PyPI; you pick the branch that matches your binding and install from there.

setup.py shows the dependency floor: PyQt5>=5.15.0, PyQt5-Frameless-Window>=0.8.0 and darkdetect. The frameless window package is what makes custom title bars and window chrome possible, and darkdetect is what lets the library follow the system light or dark preference. The extras_require block adds scipy, pillow and colorthief under the full extra, which is where AcrylicLabel and colour extraction come from. The repository layout mirrors the widget taxonomy: examples/basic_input, examples/date_time, examples/dialog_flyout, examples/layout, examples/material, examples/media, examples/menu, examples/navigation, examples/scroll, examples/status_info, examples/text, examples/view and examples/window. Reading that directory list is a faster way to learn the coverage than reading the documentation site.

One packaging detail deserves attention. The README warns that PyQt-Fluent-Widgets, PyQt6-Fluent-Widgets, PySide2-Fluent-Widgets and PySide6-Fluent-Widgets all expose the package name qfluentwidgets. Installing two of them into one environment produces an import collision that has nothing to do with your code.

## Installing PyQt-Fluent-Widgets with pip and running the gallery

The README gives two install commands. The lite version pulls only the base dependencies; the full version adds the extra packages needed for AcrylicLabel.

```bash
pip install PyQt-Fluent-Widgets -i https://pypi.org/simple/
```

That installs the PyQt5 build. If you need the acrylic label and the colour extraction that goes with it, install the extra instead.

```bash
pip install "PyQt-Fluent-Widgets[full]" -i https://pypi.org/simple/
```

The explicit index URL is not decoration. The README notes that an ImportError such as cannot import name 'XXX' from 'qfluentwidgets' usually means the installed package is too old, and the recommended fix is to reinstall against https://pypi.org/simple rather than a mirror that has not caught up. If you are on PySide6, PyQt6 or PySide2, the README says to download the code from the corresponding branch instead of using the PyPI package.

Once installed, the first real use is the gallery. The README gives this example:

```bash
cd examples/gallery
python demo.py
```

You should see the demo application window with the widget catalogue. It is the fastest way to check that the binding, the version and the styling all agree before you write any code of your own. Note that the repository file setup.py declares version 1.11.3 while the most recent release listed is v1.7.0, so the gallery you run may expose widgets that predate the tagged releases.

## The GPLv3 boundary and the Pro tier

The licence is the part most likely to decide adoption, and the README is explicit: GPLv3 for non-commercial projects, with a commercial licence available for purchase from the project's price page. GPLv3 is a copyleft licence, so linking this library into a distributed application carries obligations that a permissive licence would not. That is not a legal opinion, it is a reading of the licence identifier in the repository and the sentence in the README, and anyone shipping a closed-source product should take proper advice rather than infer from an article.

There are two separate paid products, which is easy to conflate. The Pro version is a Python library with additional components, and the README says the Pro gallery zip is downloadable from the release page for preview purposes. The C++ QFluentWidgets is a different product that requires purchasing a licence from the official website, with a compiled demo also on the release page. Separately, the Fluent Client, which integrates Designer plugins so you can drag QFluentWidgets components in Qt Designer, is sold through TaoBao and Afdian. So the free library is genuinely usable, but the Designer workflow and the extra components sit behind payment.

## Where PyQt-Fluent-Widgets is the wrong choice

The branch-per-binding model is the first real cost. A team maintaining one codebase against both PyQt6 and PySide6 cannot simply depend on the PyPI package; they either standardise on one binding or carry the branch divergence themselves. The README's own warning about the four packages sharing the qfluentwidgets name makes the multi-binding case worse, because the collision is at import time and the error message will not point at the real cause.

The second limitation is that the library is opinionated about appearance. If your product needs a design language other than Fluent, or needs to match a brand system with its own typography and spacing, you are fighting the defaults rather than using them. A stylesheet-based approach gives you a blank canvas; this gives you Windows 11.

The third is documentation depth. The README points to the website for the help document and does not document rollback, migration between major versions, or a deprecation policy. The CHANGELOG.md exists at the repository root, so version history is traceable, but the README itself offers no upgrade path guidance. If you need a library with a documented compatibility contract across releases, this is a gap you should weigh before adopting.

Finally, the release cadence visible in the repository is uneven: v1.6.0 in July 2024 and v1.7.0 in October 2024, with setup.py already at 1.11.3. The last push to the repository was on 2026-08-01, so development has continued, but the tagged releases lag well behind the declared package version.

## Alternatives and how the approach differs

The most direct alternative in the related searches is Qt-Material, which also styles Qt applications in Python. The difference is the mechanism. Qt-Material works by applying a stylesheet and a palette to the existing Qt widgets, so your code keeps using stock QWidget, QPushButton and QTableView and the appearance changes underneath. PyQt-Fluent-Widgets replaces the widgets themselves, so you instantiate library classes and get behaviour as well as paint. The stylesheet approach is lighter to adopt and easier to drop; the widget-replacement approach gives you components that a stylesheet cannot express, such as a navigation view with animated transitions or a flyout dialog, at the cost of a deeper commitment to the library.

A second reference point is the WinUI Gallery that the README cites, which is the C++ and XAML original. That is not a Python option at all, so it matters only as the design source the Python library imitates. If your application is already C++ Qt, the README points to the paid C++ QFluentWidgets rather than to this repository.

For teams that want custom widgets without a design language attached, writing them directly against Qt is still viable. The trade-off is time: a single custom-painted control is a day's work, and this library hands you a catalogue of them at the price of the GPLv3 boundary.

## Upgrade cost, maintenance signals and reporting bugs

The repository is not archived, and the last push was on 2026-08-01. That is the extent of what the repository shows about activity; there is no published support policy, no stated Python version matrix beyond the classifiers entry for Python 3, and no compatibility table for Qt minor versions. The dependency floor of PyQt5>=5.15.0 is the only stated constraint.

The upgrade risk concentrates in two places. First, the binding branches: moving from PyQt5 to PyQt6 means changing the source you install from, not just the version number. Second, the package name collision, which means an environment that once held PyQt6-Fluent-Widgets and later gets PyQt-Fluent-Widgets will not fail loudly at install time. Pinning the version and keeping one binding per environment is the practical mitigation.

For bugs, the README asks users to check the documentation first and then email shokokawaii@outlook.com with the operating system, the QFluentWidgets library version, a minimal reproducible example and reproduction steps. That is an email-based route rather than an issue tracker, even though setup.py lists a Bug Tracker URL, so expect a slower loop than a public issue thread. The Pro and C++ products are separate purchases with their own licensing, and the Fluent Client is sold through TaoBao and Afdian, so support expectations differ by tier.

## Conclusion

Adopt PyQt-Fluent-Widgets if you are building a GPLv3-compatible desktop tool and want Fluent styling without writing stylesheets by hand; the pip install and the examples/gallery demo are enough to judge it in an afternoon. Do not adopt it for a closed-source commercial product without buying the commercial licence, and do not install two of the four binding packages side by side, since they all ship as qfluentwidgets. Before committing, verify which binding branch matches your interpreter, whether the lite install covers the widgets you need or you require the full extra for AcrylicLabel, and whether the Designer workflow matters to your team, because that lives in the paid Fluent Client rather than in the library.

## FAQ

### What are widgets in PyQt?

In Qt, a widget is the base building block of a user interface, and PyQt exposes those classes to Python. PyQt-Fluent-Widgets provides its own widget classes, such as navigation views and info bars, that subclass Qt widgets and draw themselves in the Fluent style.

### Is Qt widgets free?

PyQt-Fluent-Widgets itself is licensed under GPLv3 for non-commercial projects, and the README states that commercial use requires purchasing a commercial licence. The Pro Python library, the C++ QFluentWidgets and the Fluent Client for Qt Designer are separate paid products.

### How can I create custom widgets in Qt?

One route is to subclass Qt widget classes and draw them yourself, which is what PyQt-Fluent-Widgets does across its qfluentwidgets package. The repository ships an examples directory covering categories such as basic_input, navigation, dialog_flyout and window, and the README suggests running the gallery with cd examples/gallery followed by python demo.py.

### What are all the available widgets in PyQt5?

PyQt5 supplies the stock Qt widget set, and PyQt-Fluent-Widgets adds its own Fluent-styled controls on top of it. The examples directory in this repository groups them by category, including basic_input, date_time, layout, media, menu, scroll, status_info, text and view.

## Sources

- [License: GPL-3.0](https://github.com/zhiyiYo/PyQt-Fluent-Widgets/blob/master/LICENSE)
- [Project website](https://qfluentwidgets.com)
- [README](https://github.com/zhiyiYo/PyQt-Fluent-Widgets/blob/master/README.md)
- [Releases](https://github.com/zhiyiYo/PyQt-Fluent-Widgets/releases)
- [zhiyiYo/PyQt-Fluent-Widgets on GitHub](https://github.com/zhiyiYo/PyQt-Fluent-Widgets)

---

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