Karousel: a KWin script that scrolls windows instead of squeezing them

Tiling that leaves the width to you

Karousel is a scrollable tiling KWin script, and the README says it works especially well with ultrawide screens.

The mechanism is the interesting part. A scrollable tiling window manager tiles windows but does not maximize their widths, instead it leaves the width of windows to the user's control. Windows are automatically centered when possible, and when running out of width, windows can be scrolled through horizontally.

That is a different bargain from most tiling window managers. A conventional script divides the screen into fixed columns, so on a 34 inch ultrawide you get a row of very narrow columns, or you get two screens' worth of columns with a lot of unused space at the edges. Karousel instead lets a column be as wide as you want and treats the extra screen space as something to scroll into, so a wide terminal and a document viewer can sit side by side without either being crushed.

The project sits in a family of similar window managers, and the README names three: PaperWM, Niri and Cardboard. Karousel is a KWin script rather than a standalone compositor, which is the main difference from Niri and Cardboard, and the mention of PaperWM is the closest comparison in terms of approach.

The licence is GPL-3.0, the primary language is TypeScript, and the last push was on 2026-08-23 with v0.17 tagged on 2026-06-07.

The QML modules it needs

Karousel requires three QML modules, and the list is short enough to check before you start.

They are QtQuick 6.0, org.kde.kwin 3.0 and org.kde.notification 1.0. The first two are the usual requirements for a modern KWin script, since KWin 6 is the Plasma 6 generation and the script talks to it through the KWin QML module. The third is the one people miss, because it is not a KWin module and it is not part of a default Plasma install.

The README calls this out explicitly in the installation section: first install the org.kde.notification QML module, which is the qml-module-org-kde-notifications package on Ubuntu. The Makefile in the repository confirms the dependency in practice, because the config generator emits an XML file into the package's contents/config directory, and that generated config is what registers the notification module as a dependency of the script.

The versions in the list are minimums. A script that declares org.kde.kwin 3.0 will not load on a Plasma 5 system at all, so this is a Plasma 6 script and nothing else.

Installing from a release or building it yourself

There are two routes, and the second one needs a toolchain.

The release route is simple. Download the latest release and extract it into `~/.local/share/kwin/scripts/`, which is where KWin looks for user-installed scripts. That directory layout is what the KWin script packaging expects, so an extracted release is already in the right shape.

The build route is to clone the repo and run `make install`, which requires npm, node and tsc. The Makefile shows what that actually does.

The build target compiles the TypeScript source and then generates the config:

pnpm exec tsc -p ./src/main --outFile ./package/contents/code/main.js
mkdir -p ./package/contents/config
./run-ts.sh ./src/generators/config > ./package/contents/config/main.xml

So the script logic is compiled to a single JavaScript file with tsc, and the KWin configuration XML, which holds the key bindings and the metadata, is generated from the same source of truth by a generator script. That is why the docs targets exist, since the key binding table in the README is generated too, in three formats: BBCode for the forums, Markdown, and a plain format.

Installation and removal go through kpackagetool6, the KDE packaging tool, and the install target handles both cases:

kpackagetool6 --type=KWin/Script --install=./package || kpackagetool6 --type=KWin/Script --upgrade=./package

The double invocation is deliberate, it installs if the script is not there and upgrades if it is. Removal uses the same tool with `--remove=karousel`.

The build also runs lint and test first, so `make install` will refuse to package code that fails the checks.

The key bindings and the ones that clash

The key bindings can be configured in KDE System Settings among KWin's own keyboard shortcuts, so the script does not take the shortcuts over and hide them from the system settings page.

The defaults follow a consistent scheme. Meta plus a movement key moves focus, Meta plus Shift plus the same key moves the window, and Meta plus Ctrl plus Shift moves the column. So Meta+A moves focus left, Meta+Shift+A moves the window left, and Meta+Ctrl+Shift+A moves the column left. Meta+Home and Meta+End jump to the start and the end of the strip, with the Shift and Ctrl+Shift variants doing the same for the window and the column.

Width management is a separate family. Meta+Ctrl with plus or minus increases or decreases the column width, and Meta+R cycles through preset column widths, with Meta+Shift+R cycling in reverse. Meta+Ctrl+X equalizes the widths of the visible columns, and Meta+X toggles a stacked layout for the focused column so only the active window is visible.

The caveat the README states is that Meta+D, Meta+W and Meta+S clash with default KDE shortcuts and may require manual remapping. Those three are move focus right, move focus up and move focus down, so the right-hand half of the focus movement will collide with the desktop's own shortcuts until you change them.

Several actions are deliberately left unassigned, including moving the focus to the next window in grid, moving a window to the next position in grid, increasing the window height upwards and downwards, and the column width maximum and minimum commands. That is a reasonable choice, since a script that binds everything leaves nothing for the user.

The three limitations that will decide it for you

Karousel lists its limitations in three bullets, and all three are architectural rather than bugs.

It doesn't support multiple screens. That is the one that matters most, because a tiling script that only handles one output is a non-starter for anyone with two monitors, and the fix is not a configuration change.

It doesn't support windows on all desktops. KDE's virtual desktops each hold their own set of windows, and Karousel does not manage that dimension, so windows on a desktop other than the current one are outside what the script arranges.

It doesn't support windows on multiple activities. Activities are the other KDE-specific space concept, and they are excluded for the same reason.

All three limitations come from the same root, which is that the script operates on a single linear strip of space in a single screen. A scrolling tiling model is inherently one-dimensional, and extending it to a grid of screens or to KDE's overlapping space model would change the model rather than add a feature to it.

The practical upshot is that Karousel is a script for a single ultrawide screen with one virtual desktop in use. That is a coherent target, and it is the case the README claims it works especially well with, but it is a narrow one.

The related project the README points to is kwin4_effect_geometry_change, for animations, which suggests the author treats window animations as a separate concern handled by another script rather than built into the tiler.

Editorial conclusion

Karousel fits a KDE Plasma user on a wide or ultrawide monitor who wants tiling without the fixed half-screen columns that most tiling scripts impose, and who is willing to remap a few Meta shortcuts that clash with the KDE defaults. It does not fit a multi-monitor setup, a virtual desktop or activity workflow, since all three are listed as unsupported. Before installing it, add the org.kde.notification QML module, then extract the release into `~/.local/share/kwin/scripts/`, and note that Meta+D, Meta+W and Meta+S will need manual remapping.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. peterfajdiga/karousel on GitHub
4. README
5. Releases