polonium: a tiling window manager for Plasma 6, packaged as a KWin script

A KWin script, not a standalone window manager

polonium is an autotile manager for Plasma 6, and it is an unofficial spiritual successor to Bismuth, built on KWin 6. It is also the descendant of an earlier autotile project by the same author, kwin-autotile, and the name came from a comment in that older script.

The distribution model is what makes it a KWin script rather than a program. KWin loads a script as a package, and polonium ships as a `.kwinscript` file that is installed with `kpackagetool6`, and it is listed in the KDE Store, so a user can install it from there without touching a terminal.

The feature list is short and specific:

- It works in Wayland Plasma 6.4 and up, with 6.7 recommended. - The tiling engine backend is custom and moddable. - Tile sizes are edited through the integrated KWin graphical interface. - Windows are moved and tiled with the mouse and the keyboard. - Layouts can be set independently per desktop and per screen. - DBus integration saves layouts and configurations after logging out.

The per screen and per desktop independence is the feature that separates this from a simple tiling script. Most tiling implementations apply one layout to the whole virtual desktop, and a multi monitor setup with different panel arrangements is exactly where that shows.

The project is MIT licensed, mostly, with the README noting that the majority of the project is MIT licensed, and the package metadata also records MIT. The versions are v1.2.1 from 2026-07-25, described as stable at last, v1.2.0 from 2026-06-20, and a nightly development build from 2026-09-08, with the last push on 2026-09-08.

npm and esbuild produce the script package

Building requires npm and `kpackagetool6`, and the Makefile shows exactly what happens.

# Build/Install/Clean - `make`
# Build - `make build`
# Install/Reinstall - `make install`
# Clean build - `make clean`
# Clean build and target - `make cleanall`
# Build and install DBus service - `make dbus`

The default target is `all: build install cleanall`, and there is a `.NOTPARALLEL: all` declaration so the sequence runs in order.

The build has two halves. The TypeScript source is bundled into a single ES module by esbuild, with the output written as `polonium.mjs` and then moved into the package directory as `contents/code/main.mjs`:

npx esbuild --bundle src/index.ts --outfile=polonium.mjs --format=esm --platform=neutral

The second half copies the static resources into the package layout, with `res/metadata.json` going to the package root and `res/main.xml` to `contents/config/`, `res/config.ui` to `contents/ui/` and `res/main.js` to `contents/code/`, and the QML files from `src/qml` into `contents/ui/`. Two `sed` calls then substitute the version and the name into the metadata, so the package version comes from a single variable at the top of the Makefile rather than from a hand edited file.

The result is zipped into `polonium.kwinscript` and installed with `kpackagetool6`:

kpackagetool6 -t KWin/Script -s $(NAME) \
    && kpackagetool6 -t KWin/Script -u $(PKGFILE) \
    || kpackagetool6 -t KWin/Script -i $(PKGFILE)

That command is a small piece of care. The `-s` form lists the script, the `-u` form upgrades it, and the `-i` form installs it, with the `&&` and `||` chain meaning it tries to upgrade an existing installation first and installs only if there is not one.

Dependencies are installed with `npm ci` rather than `npm install`, so the lock file is respected. The dev dependencies are esbuild, eslint, prettier, TypeScript and `kwin-api` at 6.7.1, which is the KWin script API package the code is written against.

The layout saver is a separate Rust binary

The DBus feature is not part of the KWin script. It is a separate program, in a `dbus-saver/` directory, written in Rust, and it has its own installation target.

cd dbus-saver && cargo install --path .
install -m 644 -D -t $(XDG_CONFIG_HOME)/systemd/user dbus-saver/polonium-saver.service

The systemd unit is a user unit, installed into the user's own systemd directory rather than the system one, so it starts with the session and no root is involved. The `sed` call that follows rewrites the `ExecStart` line to the full path of the installed binary, using the `CARGO_HOME` variable, because the bare command name would not be on the systemd path.

A D-Bus service file is installed into the session bus directory as well, with the name `xyz.vaughanm.poloniu...`, which is a conventional reverse domain style bus name. That is what the KWin script talks to.

The split is worth understanding as a design decision rather than a packaging detail. The KWin script lives inside the compositor process and has to stay small and responsive, and a component that has to survive a logout, hold state and answer a bus request is a different kind of program. Putting it in Rust and giving it a systemd user unit means it can be restarted independently and can outlive the script.

It also means the feature is opt-in. Without `make dbus`, the tiling works but the layouts are not saved across a logout, which is exactly the kind of thing a user discovers after a reboot.

X11 is out of scope, and bug reports have to reflect that

The X11 section is the clearest policy statement in the README. X11 is not supported, and if you encounter an issue running the script on X11, you should make sure it is reproducible in Wayland before submitting a bug report.

That is a reasonable rule, and it is worth reading it as a statement about the effort involved. A tiling window manager implemented against the KWin scripting API behaves differently under X11 and Wayland, and the differences are in the compositor's own window management rather than in the script. Without a Wayland session there is no configuration to check against, so a report from an X11 session is very likely a configuration problem being reported as a bug.

The same way of thinking shows up in the logging instructions, which are unusually detailed for a small project. You set the log level to Log in the settings, log out and log in again, and then reproduce the issue as soon as possible after logging in. Then you run a single command that collects the relevant part of the journal:

journalctl --since="$(journalctl -g "Polonium LOG: controller initialized" -n 1 --output=short-iso | cut -d ' ' -f1)" -g "[Pp]olonium" | wl-copy

The four steps the README gives for that command are: get the timestamp of the first controller message, get the journal since that message, grep for Polonium related output, and copy it to the clipboard. If you do not have `wl-copy`, the last part is removed and you copy it by hand, and for more precise logs the level is set to Debug instead of Log.

The clipboard step is a Wayland detail, and it fits the rest of the picture.

Where polonium is the wrong tool

The first wrong case is X11, which the project itself rules out. A Plasma 6 user on X11 has no supported path, and that is a large share of the people still on Plasma who have not moved to Wayland.

The second is a different desktop environment. polonium is a KWin script, so it needs KWin. A tiling window manager that works on GNOME, Sway or Hyprland is a different program, and the engine being moddable does not change that.

The third is a user on an older Plasma. The support statement is Plasma 6.4 and up, with 6.7 recommended. Plasma 5 users, who are a large installed base, are not served by this project.

The fourth is a workflow that needs the tiling to be part of the desktop rather than a script on top of it. A KWin script runs with the privileges and the restrictions of a script, and it is loaded and unloaded with the compositor. Anything that needs to survive a compositor restart, or that wants to manage displays at a lower level, is asking for something a script cannot do.

The fifth is a production expectation. The version list shows a nightly development build as the most recent tag, and the v1.2.1 release is titled stable at last, which is a light way of saying that the 1.2 line is the one to install and that things are still moving.

Editorial conclusion

Adopt polonium if you run Plasma 6 on Wayland and want tiling with a custom, moddable engine, editable tile sizes through the KWin interface, and layouts saved per screen and per desktop. Do not adopt it on X11, where the project states it is not supported, and do not adopt it if you need a tiling window manager that works across desktop environments. Before you install, note that building requires npm and `kpackagetool6`, that the project recommends Plasma 6.7 while supporting 6.4 and up, and that the DBus saver is a separate Rust component installed with `make dbus`, so the layout persistence feature only works once that unit is in place.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zeroxoneafour/polonium on GitHub