PySide6-Fluent-Widgets-Qiao

A fluent design widgets library based on PySide6

English | 简体中文 | GitHub

Install

Use uv to install the lite version:

uv add PySide6-Fluent-Widgets-Qiao

Or install the full-featured version (AcrylicLabel is available):

uv add "PySide6-Fluent-Widgets-Qiao[full]"

If you prefer pip, the equivalent commands are:

pip install PySide6-Fluent-Widgets-Qiao -i https://pypi.org/simple/
pip install "PySide6-Fluent-Widgets-Qiao[full]" -i https://pypi.org/simple/

This fork keeps the qfluentwidgets import name for compatibility, while publishing to PyPI as PySide6-Fluent-Widgets-Qiao.

The project repository is hosted at AQiaoYo/PySide6-Fluent-Widgets.

[!Warning] Don't install PyQt-Fluent-Widgets, PyQt6-Fluent-Widgets, PySide2-Fluent-Widgets, PySide6-Fluent-Widgets, and PySide6-Fluent-Widgets-Qiao at the same time, because they all expose the same import package name: qfluentwidgets.

Run Example

After cloning this repository, use uv to create the environment and run examples:

uv sync
uv run python examples/apps/gallery/demo.py

If you need the optional dependencies or documentation environment:

uv sync --extra full --group docs

You can also work with the package directly after installing it from PyPI. For example:

cd examples/apps/gallery
python demo.py

If you encounter ImportError: cannot import name 'XXX' from 'qfluentwidgets', it indicates that the package version you installed is too low. You can replace the mirror source with https://pypi.org/simple and reinstall again.

Development

Common project commands with uv:

uv run python scripts/bump_version.py
uv run python scripts/bump_version.py 2.1.0
uv run python scripts/bump_version.py --commit
uv run python scripts/bump_version.py --tag
uv run python scripts/bump_version.py --tag --push-tag
uv lock
uv build
uv run sphinx-build -b html docs/source docs/build/html

This fork publishes from the current repository. A recommended release flow is:

uv run python scripts/bump_version.py --tag --push-tag  # bump + commit + tag + push tag

Documentation

• 入门教程：从零开始，15 分钟上手
• 组件索引：全库组件速查表，附示例链接
• Sphinx 文档：docs/source/，包含主题、导航、图标等主题文档

License

PySide6-Fluent-Widgets-Qiao is distributed under GPLv3.

Copyright © 2021 by zhiyiYo. Fork maintenance and packaging changes by AQiaoYo.

Work with Designer

Fluent Client integrates designer plugins, supporting direct drag-and-drop usage of QFluentWidgets components in Designer. You can purchase the client from TaoBao or Afdian.

See Also

Here are some projects based on PyQt-Fluent-Widgets:

• zhiyiYo/Fluent-M3U8: A cross-platform m3u8 downloader
• zhiyiYo/Groove: A cross-platform music player based on PyQt5
• zhiyiYo/Alpha-Gobang-Zero: A gobang robot based on reinforcement learning

Reference

• Windows design: Design guidelines and toolkits for creating native app experiences
• Microsoft/WinUI-Gallery: An app demonstrates the controls available in WinUI and the Fluent Design System