PaperWM: scrollable tiling for GNOME Shell, and where it stops being the right tool

Who PaperWM is for, and the problem it removes

GNOME Shell's default window management is stacking: windows overlap, and you arrange them by hand or with a grid of keyboard shortcuts. PaperWM replaces that with a single horizontal strip. New windows are tiled to the right of the active window and take up as much height as possible, so the desktop becomes a sequence of columns you scroll through rather than a pile you shuffle. The README describes the project as inspired by paper notebooks and tiling window managers, and notes that while it is technically an extension, it is to a large extent built on top of the GNOME desktop rather than merely extending it. That distinction matters: PaperWM patches and reworks parts of the shell rather than adding a panel button. The audience is people who already run GNOME Shell and want tiling semantics without switching to a standalone window manager. Per monitor workspaces are the second half of the pitch, which is why the README's own search surface includes multi monitor questions. If you are happy with overlapping windows and Alt+Tab, this project solves a problem you do not have.

How the scrollable tiling and per monitor workspaces actually work

The repository is a set of JavaScript modules loaded by the shell, not a compiled binary. The top-level layout shows the split: tiling.js holds the tiling logic, workspace.js the workspace behaviour, navigator.js the keyboard navigation, minimap.js the overlay that appears while you navigate, gestures.js the touchpad handling, topbar.js the panel integration, and settings.js plus prefs.js the preferences plumbing. patches.js is the interesting one. It is where PaperWM adjusts GNOME Shell behaviour instead of only adding to it, which is the practical reason the extension is tied to specific GNOME versions. Navigation is built around a held modifier. Most keybindings grab the keyboard while Super is held down, only switching focus when Super is released, and Escape aborts the navigation and returns you to the previously active window. Super+period activates the window to the right, Super+comma the one to the left. Super+I moves the active window down into a vertical column below it, Super+O pushes the bottom window back out of that column. Activating a window scrolls the tiling so the window is fully visible. Scrolling itself works with a three finger horizontal trackpad swipe on Wayland, a swipe on a touch screen panel, or the mouse wheel over the topbar. The minimap stays visible for as long as Super is continually pressed, which is a small design decision with a large effect on how the desktop feels: the overview is a keypress, not a separate mode.

Installing PaperWM and opening your first tiled window

The recommended route is the GNOME extensions site, where the README links an install button for the extension. The source route exists for people who want to track a branch. Clone the repository, check out the branch matching your shell version, and run the installer. The README gives this exact command, with the comment as written:

make install # install, load and enable paperwm

The Makefile shows what happens underneath. It sets EXT_ID to [email protected] and TARGET to $XDG_DATA_HOME/gnome-shell/extensions/[email protected], falling back to ~/.local/share when XDG_DATA_HOME is unset. It compiles the GSettings schema, creates the extensions directory, and symlinks the repository into place. If a non-symlinked installation already exists at that path, the script prints INSTALL FAILED and exits rather than overwriting it. The installer then asks whether you want to enable PaperWM. You still have to restart GNOME Shell: log out and back in, or on X11 press alt-F2 and enter r. After logging back in, enable the extension from the Extensions application or from a terminal:

/usr/bin/gnome-extensions enable [email protected]

Once it is running, open two or three windows and press Super+period. The view should scroll sideways to bring the next window into full view, with the minimap appearing while you hold Super. Uninstalling a source install is one command:

make uninstall

If the install misbehaves, the README suggests deleting any older paperwm@... symlinks from ~/.local/share/gnome-shell/extensions and running install.sh again.

Trying PaperWM in a VM before you touch your desktop

Replacing the window management of the desktop you are currently using is not a casual experiment, and the project acknowledges this by shipping a lightweight NixOS virtual machine for trying PaperWM and for development. If Nix is installed, the README gives this command:

nix run .\#vm

There is a GPU accelerated variant as well, which needs NixGL installed first. The README lists both forms, with a note that you pick nixGLIntel or nixGLNvidia depending on your host GPU:

nixGLIntel nix run .\#vm -- -device virtio-gpu-gl -display gtk,gl=on

This is a more useful escape hatch than it first looks. Because PaperWM hooks into shell internals, a bad interaction can leave you with an awkward desktop to recover, and the VM gives you a way to learn the keybindings and the scrolling model without that risk. The trade-off is the dependency: if you do not already have Nix, this path costs you a package manager installation before it costs you anything else.

Version coupling is the real limitation

PaperWM is not a program you install once and forget. The README states that it aims to continually support current stable GNOME Shell versions, currently GNOME 47 to 49, and that new features and fixes are not generally backported to older GNOME Shell versions. Older PaperWM versions can generally be installed on older shells, and the README points to separate branches for GNOME 45-50, 42-44, 40-41 and 3.28-3.38, with the older ones marked EOL. Read that as a maintenance contract: when your distribution moves to a new GNOME release, you wait for a matching PaperWM branch rather than assuming the current one keeps working. The releases support this reading. The three most recent are v50.0.1 and v50.0.0 on 2026-04-21 and v49.0.2 on 2026-03-19, so the versioning tracks shell generations rather than a single rolling number. The last push to the repository was on 2026-09-21, which means work is ongoing, but ongoing work on the release branch does not translate into support for the shell you happen to be running. The second constraint is that this only exists for GNOME Shell. There is no macOS, Windows or KDE build, and the related searches for those platforms have no matching artefact in this repository. If you are not on GNOME, the project is simply not available to you. The third is that a source install is a symlink to your clone. Move or delete the clone and the extension breaks, which is a design choice the Makefile makes explicit rather than an accident.

PaperWM against niri, i3 and the stacking default

The comparison that matters is between PaperWM and a standalone tiling window manager such as niri or i3. Those are compositors or window managers in their own right: you log into them instead of GNOME, and they own the entire session. PaperWM is the opposite arrangement. It keeps GNOME Shell, its settings, its extensions and its applications, and changes how windows inside that shell are laid out. You get tiling without giving up the GNOME ecosystem, and in exchange you inherit GNOME's release cadence and the version coupling described above. A standalone compositor has no such dependency on a shell it does not use. The other comparison is against GNOME's own stacking behaviour. PaperWM is not a grid extension that snaps windows into a fixed set of slots. The strip is unbounded and scrollable, which is why the minimap exists at all: with a fixed grid you can see everything at once, and with a scrollable strip you cannot. That is the central trade-off of the design. If you want to see every window simultaneously, a grid or the default stacking model is a better fit than a strip you scroll.

Configuration, licence and the cost of keeping up

PaperWM installs a user configuration file on first run, and the README points to a user configuration and development section for it. The Makefile names the files involved: config/user.js and config/user.css, alongside the GSettings schema at schemas/org.gnome.shell.extensions.paperwm.gschema.xml. Keybindings are changed through the extension settings under Extensions, then PaperWM, then Settings; the repository ships example files at examples/keybindings.js, examples/layouts.js and examples/winprops.js for the JavaScript side. Because the extension is a symlink to your clone, editing those files and reloading is the development loop, which is presumably why the README routes contributors to the develop branch. The README is explicit that pull requests submitted to the release branch will not be accepted, and that a PR accidentally opened against release is automatically retargeted to develop. The project is licensed GPL-3.0, and the LICENSE file is included in the release file list, so a source install carries the usual copyleft obligations; if you plan to redistribute a modified build, read the licence itself rather than relying on a summary. Upgrade cost is the part people underestimate. Each GNOME release is a potential break, the fix lands on a new branch, and you reinstall from that branch. Budget for that rather than treating PaperWM as a one-time install.

Editorial conclusion

PaperWM suits GNOME Shell users on a supported release who want tiling without leaving the GNOME desktop, and who are willing to re-login after upgrades. It is the wrong choice if you run KDE, macOS or Windows, or if you need a window manager that is not an extension. Verify your GNOME Shell version against the branch table in the README before you clone anything, and check the develop branch if you plan to submit a patch.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. paperwm/PaperWM on GitHub
3. Project website
4. README
5. Releases