qtframelesskit

Modern, cross-Qt frameless window framework for Windows in pure Python.

---

Overview

qtframelesskit is a modern, lightweight, pure-Python framework for building native-feeling frameless windows in Qt on Windows.

Standard Qt frameless windows (Qt.WindowType.FramelessWindowHint) strip away crucial operating system capabilities: native DWM drop shadows, smooth window resize borders, Windows 11 Snap Layout menus, and modern backdrop materials like Mica and Acrylic.

qtframelesskit restores these native Win32 window mechanics through ctypes and pywin32—with zero C++ compilation or binary wheel dependencies required.

---

Screenshots

Windows 11

Windows 10

---

Installation

Install qtframelesskit with your preferred Qt binding:

# With PySide6 (recommended)
pip install qtframelesskit[pyside6]

# With PyQt6
pip install qtframelesskit[pyqt6]

# If you already have a Qt binding installed
pip install qtframelesskit

---

Quick Start

1. Standard Frameless Window

A standard frameless window featuring native DWM drop shadows, rounded corners, custom border color, and full Snap Layouts support:

import sys
from PySide6.QtWidgets import QApplication, QLabel
from qtframelesskit import FramelessMainWindow, WindowCornerPreference


class MainWindow(FramelessMainWindow):
    def __init__(self) -> None:
        super().__init__()
        self.setWindowTitle("QtFrameless Demo")
        self.resize(800, 500)

        # Configure Windows 11 styling
        self.windowCornerPreference = WindowCornerPreference.ROUND
        self.borderColor = "#696969"

        # Add content to central widget
        centralWidget = self.centralWidget()
        if centralWidget is not None and centralWidget.layout() is not None:
            centralWidget.layout().addWidget(QLabel("Welcome to qtframelesskit!"))


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec())

2. Windows 11 Mica MainWindow

Leverage the native Windows 11 Mica backdrop material:

import sys
from PySide6.QtWidgets import QApplication, QLabel
from qtframelesskit import FramelessMicaMainWindow, WindowCornerPreference


class MicaWindow(FramelessMicaMainWindow):
    def __init__(self) -> None:
        super().__init__(isAlt=False)
        self.setWindowTitle("Windows 11 Mica")
        self.resize(800, 500)
        self.windowCornerPreference = WindowCornerPreference.ROUND

        centralWidget = self.centralWidget()
        if centralWidget is not None and centralWidget.layout() is not None:
            centralWidget.layout().addWidget(QLabel("Native Mica backdrop window"))


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MicaWindow()
    window.show()
    sys.exit(app.exec())

Tip: Set isAlt=True or call self.setIsAlt(True) to enable Mica Alt (tabbed material).

3. Windows Fluent Acrylic MainWindow

Apply native Windows Fluent Acrylic blur-behind material with custom tint color:

import sys
from PySide6.QtWidgets import QApplication, QLabel
from qtframelesskit import FramelessAcrylicMainWindow, WindowCornerPreference


class AcrylicWindow(FramelessAcrylicMainWindow):
    def __init__(self) -> None:
        # Tint format: RRGGBBAA
        super().__init__(gradientColor="20202099")
        self.setWindowTitle("Windows Acrylic Material")
        self.resize(800, 500)
        self.windowCornerPreference = WindowCornerPreference.ROUND

        centralWidget = self.centralWidget()
        if centralWidget is not None and centralWidget.layout() is not None:
            centralWidget.layout().addWidget(QLabel("Native Acrylic blur backdrop"))


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = AcrylicWindow()
    window.show()
    sys.exit(app.exec())

4. Integrated Title Bar MenuBar & Centered Title

Seamlessly embed a QMenuBar directly into the title bar alongside a centered window title:

import sys
from PySide6.QtCore import Qt
from PySide6.QtWidgets import QApplication
from qtframelesskit import FramelessMainWindow


class Window(FramelessMainWindow):
    def __init__(self) -> None:
        super().__init__()
        self.setWindowTitle("Example MainWindow")
        self.resize(800, 500)

        # 1. Center the title in the title bar
        self.getTitleBar().setTitleAlignment(Qt.AlignmentFlag.AlignCenter)

        # 2. Add menus directly to the integrated title bar menu bar
        menuBar = self.menuBar()
        fileMenu = menuBar.addMenu("File(&F)")
        fileMenu.addAction("New(&N)")
        fileMenu.addAction("Open(&O)")

        editMenu = menuBar.addMenu("Edit(&E)")
        editMenu.addAction("Undo(&U)")
        editMenu.addAction("Redo(&R)")


if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = Window()
    window.show()
    sys.exit(app.exec())

---

Windows Compatibility

qtframelesskit automatically detects the host Windows OS build at runtime and gracefully enables or falls back on visual effects:

Feature	Windows 11 22H2+ (Build ≥ 22621)	Windows 11 21H2 (Build ≥ 22000)	Windows 10 1809+ (Build ≥ 17763)
Frameless DWM Drop Shadows	Full	Full	Full
Snap Layouts Hover Menu	Full	Full	—
DWM Rounded Corners	Full	Full	—
Mica Material	Full	Full	—
Mica Alt (Tabbed Material)	Full	—	—
Acrylic Blur-Behind	Full	Full	Full
Dark / Light Theme Sync	Full	Full	Full
Per-Monitor DPI Scaling	Full	Full	Full

Note: On non-Windows platforms, importing qtframelesskit raises PlatformNotSupportedError.

---

Acknowledgments & Inspiration

Special thanks and credit to the open-source projects that inspired and informed this framework:

• qwindowkit by stdware: An outstanding C++ window customization framework for Qt, which served as a primary architectural inspiration for native frameless mechanics, Windows 11 Snap Layout hit-testing, and modern DWM composition patterns.

---

License

This project is licensed under the terms of the MIT License.