PyQt-Frameless-Window gives a Qt app a native title bar on three platforms

A frameless window with the platform blur underneath

PyQt-Frameless-Window is a cross-platform frameless window based on PyQt and PySide, supporting Win32, Linux and macOS.

The value of a frameless window is that the title bar and the frame become your own widgets, so an application can look like it was designed rather than assembled. What usually makes that work painful is that the window then has to do the work the system used to do, and the visual effects the platform provides are only reachable through platform-specific calls.

That is what this library takes care of. The feature list is short and platform-shaped. Moving and stretching the window. Window shadow and window animation. Win11 snap layout. Win10 acrylic blur, Win11 mica blur and Win7 Aero blur. A macOS blur. And disabling screen capture.

The blur list is the interesting part, because it is the same feature on four different operating systems and it is implemented four different ways. Win10 acrylic and Win7 Aero are DWM composition effects, Win11 mica is the newer material-based backdrop, and the macOS one is a different system entirely. The library exposes them as one setting so that the same application code produces a native look on each platform.

Disabling screen capture is the other one that is not cosmetic. The examples directory includes a screen_capture_filter.py, which suggests the mechanism is a filter on the window's content rather than a global toggle.

The project is Python, GPLv3 licensed, with the last push on 2026-08-02. The release history is v0.8.0 from 2026-02-07, v0.7.0 from 2025-05-10 and v0.4.0 from 2024-08-17, and the package file carries version 0.8.2, so the published package is a little ahead of the newest tag.

Installing is a pip install, and the platform dependency differs

To install, use pip:

pip install PyQt5-Frameless-Window

Or clone the repository:

git clone https://github.com/zhiyiYo/PyQt-Frameless-Window.git
python setup.py install

The requirements table is the part to read before you pick a platform, because the dependency is different on each one: pywin32 on Win32, xcffib on Linux and pyobjc on MacOS.

Those are not interchangeable choices. pywin32 is the Windows API binding, and it is what the library uses to talk to the window manager for the acrylic, mica and Aero effects and for the snap layout. xcffib is an X11 protocol library, and it is the Linux equivalent. pyobjc is the Objective-C bridge on macOS, and the package file lists both pyobjc and PyCocoa as install requirements on Darwin.

The requirements file pins the versions more tightly than the setup file does: pywin32 at 227 on win32, xcffib at 0.11.1 on linux, and unpinned pyobjc and PyCocoa on darwin. The setup file expresses the same dependencies as environment markers, so a pip install pulls only the one your platform needs.

That is worth pausing on, because the Linux dependency being xcffib rather than a Wayland library tells you something about the scope. The library speaks X11 on Linux, which is what the reference project it points to, framelesshelper, also lists alongside X11, Wayland and macOS. On a modern Wayland-only session the native client-side decorations are back, and a frameless window is either unnecessary or has to be done through the portal instead.

Using it means subclassing FramelessWindow

To use the frameless window, you only need to inherit `FramelessWindow` or `FramelessMainWindow`, and here is a minimal example:

import sys

from PyQt5.QtWidgets import QApplication
from qframelesswindow import FramelessWindow


class Window(FramelessWindow):

    def __init__(self, parent=None):
        super().__init__(parent=parent)
        self.setWindowTitle("PyQt-Frameless-Window")
        self.titleBar.raise_()


if __name__ == '__main__':
    app = QApplication(sys.argv)
    demo = Window()
    demo.show()
    sys.exit(app.exec_())

The two lines that do the work are `super().__init__(parent=parent)` and `self.titleBar.raise_()`. The first is the base class doing the platform work, and the second is the interesting one: the title bar is a widget inside the window, and raising it puts it above your content so that your layout does not cover it.

The import name is `qframelesswindow`, which is the module name, while the distribution is `PyQt5-Frameless-Window` and the project is PyQt-Frameless-Window. Those three names being different is a small papercut when you are searching for the package, and it is also why the `setup.py` name field is PyQt5-Frameless-Window even though the project supports more than PyQt5.

For more complex requirements, the documentation points at two example files: demo.py and main_window.py. The examples directory also holds acrylic_demo.py, web_engine.py and the screen_capture_filter.py, so the library is demonstrated against a Qt WebEngine view and against the capture filter, which are the two cases most likely to break a custom frame.

The notes section is where the honest limits are

The project keeps a numbered notes list, and it is more useful than the feature list because it tells you what will go wrong.

Note 1 is about the default title bar. `FramelessWindow` provides a default custom title bar, and if you do not like it, you rewrite it, as demo.py does.

Note 2 is the one that would stop me shipping this. Moving the acrylic window on Win10 may get stuck, and at present there is no good solution. The suggested workaround is that you could disable the acrylic effect when moving the window, but the author says this has not been done in the source code. So the fix is yours to implement, and the affected configuration is the Windows 10 acrylic one.

Note 3 is that snap layout is not enabled by default, with a link to issue 56 for how to turn it on.

Note 4 is the Windows import error, the DLL load failed while importing win32api, which is a pywin32 installation problem rather than a library problem, and the author points to a Stack Overflow answer and a blog post.

Note 5 is the one that decides the whole adoption question for many people. If you are using PySide2, PySide6 or PyQt6, you can download the code in the PySide2, PySide6 or PyQt6 branch. The default branch is the PyQt5 one, so if you are on any of the other bindings you are not using the published package, you are using a branch of the source tree, and you are taking on the consequence of that.

The topics list confirms the scope: pyqt5, pyqt6, pyside, pyside2 and pyside6 all appear, alongside acrylic, mica and cross-platform.

Where this sits against the other frameless window options

The realistic alternatives are three, and they differ in what they expect of you.

The first is the reference project the documentation points to, wangwenx190/framelesshelper, described as providing frameless windows for Qt Widgets and Qt Quick applications and supporting Win32, X11, Wayland and macOS. The coverage is broader on Linux, and the fact that it is listed as a reference rather than a dependency suggests the two projects are peers rather than one wrapping the other.

The second is doing it yourself with the native window procedures, which means calling SetWindowLong on Windows to remove the frame and then handling WM_NCHITTEST yourself so the window can still be dragged and resized. That is the classic approach, it gives you full control, and it is a day of work per platform with a lot of fiddly constants. This library exists so that you do not do that.

The third alternative is not doing it at all and using the system frame, which on Windows 11 with rounded corners and Mica in the system title bar is not as bad as it was. A native-looking frame is free, always correct, and resizes itself for the display scaling. The reason to give that up is a design requirement, not a technical one.

A caveat on the alternatives is licensing. This project is GPLv3, and so is the reference project it points at. For a commercial application that is a real consideration, since a GPL library linked into your application has implications for how you distribute it.

The projects that use this library are worth reading as a signal. The documentation lists QFluentWidgets, a fluent design widgets library based on Qt, Groove, a cross-platform music player based on PyQt5, and Alpha-Gobang-Zero, a gobang robot based on reinforcement learning. All three are the same author's applications, and all three are the kind of thing that wants a custom frame.

Editorial conclusion

Adopt PyQt-Frameless-Window if you are building a desktop application in Python with Qt and want a custom title bar and the Windows 11 or macOS translucent background without writing platform code yourself, because the library handles the per-platform window procedure for you. Skip it if you need a fully supported desktop application for end users, since the project is a personal library with two documented rough edges and no Windows CI story described, and it is GPLv3 which is heavier than most application authors want. Verify first that the PySide2, PySide6 or PyQt6 branch matches the Qt binding you use, since the published package is the PyQt5 one, and that your platform's dependency is installed, pywin32 on Windows, xcffib on Linux and pyobjc with PyCocoa on macOS.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. zhiyiYo/PyQt-Frameless-Window on GitHub