# KWin: the Wayland compositor that insists on being invisible > KWin is the Wayland compositor behind KDE Plasma, and its own documentation is unusually strict about what it will not become, listing a set of conditions any new feature must satisfy and putting every new feature on probation for two releases. **KDE/kwin** — Easy to use, but flexible, Wayland Compositor - Repository: https://github.com/KDE/kwin - Website: https://invent.kde.org/plasma/kwin - Stars: 707 · Forks: 168 - Language: C++ - License: not declared - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/kde-kwin ## KWin describes itself by what it refuses to be The unusual thing about the KWin documentation is that its clearest statement of purpose is a list of negations. KWin is not a standalone Wayland compositor, and the project points at labwc and sway as the kind of compositor it is not. It is not a replacement for window managers designed for a specific desktop shell, and GNOME Shell is the example given. It is not a minimalistic window manager. And it is not designed for network transparency, although the project notes that this is possible with something like waypipe. That last point deserves a second reading, because it is the one item on the list that reads as a limitation rather than a boundary. The stated primary usage is alongside a desktop shell such as KDE Plasma Desktop, and the project says it follows the targeted user group of whichever shell uses it as its window manager. ## The design mission is that you should not notice the compositor KWin is described as easy to use but flexible, and the stated goal is that it goes out of the way, so that users should not notice they use a window manager at all. The same paragraph then concedes that it provides a steep learning curve for advanced features, which are available as long as they do not conflict with the primary mission. That tension is the design, not an accident: the everyday path is meant to be invisible and the advanced path is meant to be deep. The repository structure reflects the same split, with src/ for the compositor itself, data/ for its resources, po/ for translations, doc/ for documentation, and a separate examples/ directory holding a plugin example, a quick effect and a quick script, which tells you the extension surface is a first-class part of the project rather than an afterthought. ## Ten conditions any new KWin feature has to clear The contributing document includes a set of guidelines for new features, and it reads more like a review checklist than a wish list. A feature can only be added if it does not violate the primary mission, does not introduce instabilities, is maintained, meaning bugs are fixed in a timely manner by the second next minor release if it is not a corner case, works together with all existing features, supports both single and multi screen, adds a significant advantage, is feature complete in the sense of supporting at least all useful features from competitive implementations, is not a special case for a small user group, does not increase code complexity significantly, and does not affect the licence, which the document names as GPLv2+. The feature complete condition is the strictest of the set, since it is measured against competitors rather than against the existing code, and it is the one that most clearly tells a contributor what a proposal has to argue. ## New features ship on probation and get removed again The most unusual rule in the document is the probation period. All newly added features are under probation, meaning that if any of the non-functional requirements listed do not still hold true in the next two feature releases, the feature will be removed again. Read as a process, this inverts the usual relationship between a project's backlog and its released surface. Nothing is permanent on arrival, and the two-release window is the project's way of saying that a feature which turns out to be unstable, or which quietly raises the code complexity, will be withdrawn rather than left to rot. The same non-functional requirements are stated to hold for any kind of plugin, whether effects or scripts, and the project suggests using scripted plugins and distributing them separately. ## The build is CMake with KDE's own CI on top There is no install recipe in the project overview, and the pointer for that is the contributing document, which the overview says contains everything you need to get started contributing to KWin. What the repository does show is the shape of the build. KWin is written in C++ and builds with CMake, with a CMakeLists.txt at the root and a KWinConfig.cmake.in and a KWinDBusInterfaceConfig.cmake.in for the generated configuration. The KDE-specific tooling is visible too: a .kde-ci.yml for the project's own CI configuration and a .gitlab-ci.yml, both of which point at a hosted pipeline rather than a GitHub Actions setup. Static analysis has its own files, with a cppcheck-suppressions.xml and a kwin-cppcheck.xml for the check itself, plus a .clang-format for formatting and a .git-blame-ignore-revs file for the revisions that a formatting pass introduced, which is the convention for keeping blame history readable. There is also a kconf_update/ directory for configuration migration, the mechanism KDE uses to move a stored setting to a new format without breaking a running session. ## Autotests, a service unit file and a D-Bus interface The repository separates its tests into two directories, autotests/ and tests/, which suggests unit-level and integration-level coverage kept apart, and the examples/ directory with a plugin, a quick effect and a quick script doubles as documentation for how to write one. The generated D-Bus interface configuration shows that the compositor exposes a D-Bus interface, and there is a plasma-kwin_wayland.service.in file, a systemd unit template for running the compositor as a Wayland session service. That combination is what you would expect from a component that a desktop shell starts on login and talks to over D-Bus, and it is the reason the documentation insists that KWin is not usable as a standalone compositor: the D-Bus surface and the session integration are the product, and they are shaped for a shell. ## Where to ask questions, and who answers them The support section of the project overview draws two clear lines. Application developers with questions about windowing systems, whether X11 or Wayland, are invited to contact the team directly, and the project says not to hesitate. End users are pointed at the support channels of their Linux distribution, with the explicit statement that the KWin development team does not provide end user support. For contributors there is an IRC channel, #kde-kwin on irc.libera.chat, and a Matrix room at kwin:kde.org, both linked from the overview. Bugs go to KDE's bugtracker and should be filed for product KWin specifically, which matters because the tracker covers all of KDE and a misfiled report lands in the wrong queue. Sensitive reports, and security feedback in general, can be raised privately by email, with the security policy in the SECURITY.md file. ## Conclusion KWin fits a desktop developer building on KDE Plasma who needs the compositor's scripting and effect surface, and it fits a contributor who wants a project with an explicit written policy on what belongs in a window manager, since the feature guidelines are the most concrete statement of scope in the documentation. It does not fit someone who wants a standalone Wayland compositor, because the documentation says plainly that KWin is not one and provides no functionality belonging to a desktop shell, and it does not fit a user who expects the development team to answer support questions, since the project directs end users to their Linux distribution's support channels. Before you file a feature request, check it against the ten conditions in the contributing guide, because a proposal that fails the stability or code complexity condition will not be accepted, and if you are a plugin author, use the scripted plugin route the project suggests so your code is distributed separately. ## FAQ ### What is KWin and what is it not? KWin is a flexible Wayland compositor for Linux, used together with a desktop shell such as KDE Plasma. The project states it is not a standalone Wayland compositor, not a replacement for shell-specific window managers such as GNOME Shell, not a minimalistic window manager, and not designed for network transparency, though that is possible with something like waypipe. ### What conditions must a new KWin feature satisfy? The contributing guide lists ten: it must not violate the primary mission, must not introduce instabilities, must be maintained with bugs fixed by the second next minor release, must work with all existing features, must support single and multi screen, must add a significant advantage, must be feature complete against competitive implementations, must not be a special case for a small user group, must not significantly increase code complexity, and must not affect the GPLv2+ licence. ### Why can a KWin feature be removed after it ships? All newly added features are under probation for two feature releases. If any of the non-functional requirements no longer holds in that window, the feature is removed again, and the same requirements are stated to apply to plugins such as effects and scripts. ### Where should KWin bugs and questions go? Bugs go to KDE's bugtracker filed for product KWin. Application developers with questions about X11 or Wayland can contact the team, while end users are directed to the support channels of their Linux distribution, since the development team does not provide end user support. ## Sources - [Issues](https://github.com/KDE/kwin/issues) - [KDE/kwin on GitHub](https://github.com/KDE/kwin) - [Project website](https://invent.kde.org/plasma/kwin) - [README](https://github.com/KDE/kwin/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kde-kwin