fluentqml 0.2.5

A Fluent Design-like UI library for Qt Quick (QML) based on PySide6

FluentQML

Fluent Design components for PySide6 and Qt Quick.

English | 中文

[!IMPORTANT] FluentQML is a secondary development based on RinUI RinUI is licensed under the MIT License, and the original copyright notice is preserved in this repository's license file.

Overview

FluentQML is a PySide6 + QML component library for building desktop interfaces with a Fluent Design inspired look and feel. It provides reusable Qt Quick controls, window chrome, theme handling, icon support, translation loading, and a gallery app that demonstrates the available components.

The project is designed for developers who want to keep their application UI in QML while using Python for application startup, window management, configuration, and platform integration.

Compared with RinUI

FluentQML currently adds these changes:

• macOS native window materials: System, HUD, and None.
• Better macOS window handling, including native title-bar integration and smoother window dragging.
• Windows 11 Snap Layout support for custom windows.
• QML, fonts, images, and translations compiled into Qt qrc resources for PyPI packages.
• Cross-platform Python scripts for resource building, Gallery packaging, and releases.
• Fixes for CalendarDatePicker, Expander rounded corners, page refresh behavior, and config paths.

Features

• Fluent-style Qt Quick controls for common desktop UI patterns
• Custom application windows with title bar and navigation layouts
• Light, dark, and automatic theme switching
• Theme color and backdrop effect support
• Fluent System Icons integration
• Translation resource loading for application localization
• Gallery examples for controls, layouts, navigation, dialogs, menus, and inputs
• PyInstaller hook support for packaged applications

Preview

Installation

Install from PyPI after the package is published:

pip install fluentqml

For local development, install this repository in editable mode:

git clone https://github.com/Cheukfung/fluentqml.git
cd fluentqml
uv sync

If you are not using uv, install the runtime dependencies manually:

pip install PySide6 darkdetect

Quick Start

Create a QML file, for example main.qml:

import QtQuick
import FluentQML

FluentWindow {
    visible: true
    width: 900
    height: 600
    title: "FluentQML App"

    Text {
        anchors.centerIn: parent
        text: "Hello FluentQML"
    }
}

Launch it from Python:

import sys

from PySide6.QtWidgets import QApplication
from fluentqml import FluentQMLWindow

app = QApplication(sys.argv)
window = FluentQMLWindow("main.qml")
sys.exit(app.exec())

The QML import name is FluentQML; the Python package name is fluentqml.

Gallery

Run the gallery app from the repository root:

uv run python examples/gallery.py

Or, if you are managing dependencies yourself:

python examples/gallery.py

The gallery is the best place to inspect available controls and copy working usage patterns while the formal documentation is still being written.

Project Layout

fluentqml/              Core Python package, QML modules, resources, hooks
examples/               Gallery app and component usage examples
docs/                   Images and documentation drafts
scripts/                Resource and release helper scripts
test/                   Small local QML loading experiments

Development

Regenerate the Qt resource bundle after changing QML, fonts, images, or translation files:

uv run python scripts/build_fluentqml_qrc.py

Run lint checks:

uv run ruff check .

Update library translations:

uv run python scripts/update_ts.py library

Update Gallery translations:

uv run python scripts/update_ts.py gallery

Package the Gallery app with PyInstaller:

uv run python scripts/package_gallery.py

Build release artifacts:

uv run python scripts/release.py build

The release script cleans dist/, regenerates fluentqml_rc.py, builds the sdist and wheel, verifies that the wheel contains fluentqml/fluentqml_rc.py, checks that raw QML resources are not accidentally included in the wheel, and runs twine check.

Upload the already-built artifacts to TestPyPI:

uv run python scripts/release.py upload-testpypi

Upload the same artifacts to PyPI after testing the TestPyPI install:

uv run python scripts/release.py upload-pypi

Useful naming conventions in this project:

• Python import: from fluentqml import FluentQMLWindow
• QML import: import FluentQML
• Qt resource prefix: qrc:/FluentQML
• Generated resource module: fluentqml.fluentqml_rc

Credits

FluentQML uses resources and ideas from the wider Qt and Fluent ecosystem:

• PySide6 and Qt Quick
• Fluent Design System
• Fluent UI System Icons
• WinUI 3 Gallery

License

FluentQML is released under the MIT License. See LICENSE for the full license text.

Copyright (c) 2026 Cheukfung