FluentPySide

fluentpyside packages the FluentWinUI3 Qt Quick Controls style so any Qt / PySide6 application can add the FluentWinUI3 theme easily. The goal is to make it simple to enable the Fluent theme without bundling the full PySide6 runtime into your application. For minimal, bloat-free builds prefer installing PySide6-Essentials on the target system rather than packaging compiled plugin binaries inside this package.

⚠️ IMPORTANT — Read this before using

This library is a QML visual theme only. It styles Qt Quick Controls 2 components (Button, TextField, CheckBox, etc.) to look like Windows 11's Fluent Design. It does NOT provide:

• A Python widget library (it does NOT touch QtWidgets — no QPushButton, QLabel, etc.)
• Custom QML components — you use the standard Qt Quick Controls 2 API, this library just changes how they look

For colors and design tokens, use the Fluent singleton (available after calling fluentpyside.apply()):

Rectangle {
    color: Fluent.cardBackground
    radius: Fluent.radiusMedium
    Label {
        text: "Hello"
        color: Fluent.textPrimary
        font.pixelSize: Fluent.fontBodySize
        font.family: Fluent.fontFamily
    }
}

Quick Start

pip install PySide6-Essentials   # recommended — provides the runtime plugins
pip install fluentpyside

import fluentpyside
fluentpyside.apply()

That's it. apply() registers the FluentWinUI3 QML import path and sets the QtQuickControls2 style to FluentWinUI3. After that, any standard Qt Quick Controls 2 component in your QML will be rendered with the Fluent theme automatically.

How it works

You write standard QML using the normal Qt Quick Controls 2 imports. The fluentpyside.apply() call sets the style, so every component automatically gets the Fluent look — you don't import anything special, you don't reference any theme object, you just write normal QML.

# main.py
from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine
import fluentpyside

app = QGuiApplication([])
engine = QQmlApplicationEngine()

# ONE line — this is all you need
fluentpyside.apply()

engine.load("main.qml")
app.exec()

// main.qml
// NOTE: Only standard Qt imports — NO Fluent-specific import needed
import QtQuick
import QtQuick.Controls
import QtQuick.Layouts

ApplicationWindow {
    visible: true
    width: 400
    height: 300
    title: "FluentWinUI3 Demo"

    ColumnLayout {
        anchors.fill: parent
        anchors.margins: 16
        spacing: 12

        Label {
            text: "FluentWinUI3 Theme"
            font.pixelSize: 20
            font.bold: true
        }

        TextField {
            placeholderText: "Type something..."
            Layout.fillWidth: true
        }

        Button {
            text: "Click me"
            onClicked: console.log("Button clicked!")
        }

        CheckBox {
            text: "Enable feature"
        }

        Switch {
            text: "Dark mode toggle"
        }

        ProgressBar {
            value: 0.6
            Layout.fillWidth: true
        }

        ComboBox {
            model: ["Option 1", "Option 2", "Option 3"]
            Layout.fillWidth: true
        }

        Item { Layout.fillHeight: true }
    }
}

Available styled components

These standard Qt Quick Controls 2 components get Fluent styling automatically when fluentpyside.apply() is called:

That's 52 styled components covering the full Qt Quick Controls 2 API. All components automatically switch between light and dark mode.

Gallery Demo

A comprehensive gallery showcasing every control is included. Run it with:

cd examples
python run_gallery.py

Fluent Design Tokens

After calling fluentpyside.apply(), a Fluent singleton is available in your QML with WinUI 3 design tokens. All colors automatically switch between light and dark mode based on the system preference (Fluent.isDark).

Example usage

import QtQuick
import QtQuick.Controls

ApplicationWindow {
    visible: true; width: 600; height: 400

    Rectangle {
        anchors.fill: parent
        color: Fluent.background

        ColumnLayout {
            anchors.centerIn: parent

            Label {
                text: "Welcome"
                color: Fluent.textPrimary
                font.pixelSize: Fluent.fontTitleSize
                font.family: Fluent.fontFamily
            }

            Button {
                text: "Accent Button"
                Layout.alignment: Qt.AlignHCenter
            }

            Rectangle {
                width: 200; height: 4
                radius: Fluent.radiusSmall
                color: Fluent.accent
                Layout.alignment: Qt.AlignHCenter
            }
        }
    }
}

Available properties

Surface Colors

Text Colors

Accent Colors

Control Colors

Input / Text Field Colors

Border / Divider

Status Colors

Typography

Spacing

Radius

Requirements

• Python 3.8+
• PySide6-Essentials (recommended) or PySide6 — provides the Qt runtime plugins needed at runtime. This package only ships the QML styling files (no compiled plugin binaries), keeping the wheel small and cross-platform.

Public API reference

fluentpyside.apply() -> str

One-liner to enable the FluentWinUI3 theme. Call this before loading any QML. Returns the path used for the style.

import fluentpyside
fluentpyside.apply()  # call BEFORE engine.load()

fluentpyside.set_style(engine=None, path=None) -> str

Lower-level API if you need fine-grained control. Sets the QML import path and Qt Quick Controls 2 style.

engine = QQmlApplicationEngine()
style_path = fluentpyside.set_style(engine=engine)
engine.load("main.qml")

fluentpyside.install_assets(target_dir)

Copy the FluentWinUI3 QML tree into a target project directory. Useful for vendoring the theme files.

python -m fluentpyside --install /path/to/your/project

fluentpyside.find_installed_style() -> Optional[Path]

Search for the FluentWinUI3 style in the installed PySide6 package. Returns None if not found.

fluentpyside.default_style_path() -> Path

Return the package-local style path (inside the fluentpyside wheel).

Common mistakes

❌ "ReferenceError: Fluent is not defined"

Make sure you call fluentpyside.apply() before loading your QML. The Fluent singleton is only available after the style is applied:

engine = QQmlApplicationEngine()
fluentpyside.apply()  # ✅ Fluent singleton is now available
engine.load("main.qml")

❌ Using Qt Widgets instead of Qt Quick

This library styles Qt Quick Controls 2 (QML) only. It does nothing for classic Qt Widgets:

# ❌ These are Qt Widgets — NOT styled by fluentpyside
from PySide6.QtWidgets import QPushButton, QLabel, QMainWindow

# ✅ Use QML with PySide6 — this IS styled
from PySide6.QtQml import QQmlApplicationEngine

❌ Calling apply() after loading QML

fluentpyside.apply() must be called before engine.load():

engine = QQmlApplicationEngine()
fluentpyside.apply()  # ✅ BEFORE
engine.load("main.qml")

# NOT:
# engine.load("main.qml")  # ❌ too late
# fluentpyside.apply()

❌ Forgetting PySide6-Essentials

This package only ships QML files. You need PySide6 installed for the runtime:

pip install PySide6-Essentials  # or PySide6 (full)
pip install fluentpyside

Updating the theme in a project

If you want to copy the FluentWinUI3 QML tree into a target project manually:

python tools/update_theme.py /path/to/your/project

This copies FluentWinUI3/ into /path/to/your/project/QtQuick/Controls/FluentWinUI3/ so you can add the project root as a QML import path.

License

• Wrapper: MIT License (file LICENSE)
• Upstream QML assets: copied from the locally installed PySide6 / PySide6-Essentials package. Follow Qt/PySide licensing when redistributing.