PaperWM turns GNOME Shell into a scrollable tiling desktop
Tiled scrollable window management for GNOME Shell
At a glance
- What is it?
- PaperWM is a GNOME Shell extension that tiles windows into a horizontally scrollable strip and gives every monitor its own workspace. It suits GNOME users who want tiling without leaving the shell, and it costs you a shell that no longer matches stock GNOME.
- Who is it for?
- Adopt PaperWM if you already live in GNOME and want a tiling strip without swapping your compositor, and pass on it if you need a session that survives GNOME version bumps untouched, or if you are already on the KDE or macOS side where nothing here applies.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- paperwm/PaperWM4,382 ★ · +69
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| paperwm/PaperWM | 4.3k | 4.4k |
69 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A tiling layer grafted onto the GNOME session itself
PaperWM does not replace your window manager. It loads into GNOME Shell as an extension, grabs input, and rewrites how the shell lays out windows. That distinction drives everything else about the project.
The strip is horizontal. New windows tile to the right of the active window and take as much height as they can. The strip is wider than the monitor, so PaperWM scrolls it, which is why activating a window scrolls the tiling to make it fully visible rather than rearranging the layout to fit. Activating a window by clicking its edge on the monitor is the mouse path into the same operation.
Navigation is directional and relative. Super and the period key activates the window to the right, Super and the comma key the window to the left. Those two keys carry the < and > markings on a US keyboard and keep that order on most other layouts, which is a deliberate choice about which keyboard layouts will not need remapping. Navigating brings up a minimap that stays on screen for as long as Super is held down, so you can see where you are in a strip that extends past both edges of the display.
Restacking is separate from moving. Super and I moves the window to the right below the active window, tiling the pair vertically in a column. Super and O pushes the bottom window back out of that column.
Super is a grab, not a modifier, and Escape is the undo
Holding Super does not let you type another window's shortcut. PaperWM grabs the keyboard while Super is down and only commits the focus switch when you let the key go. Escape during the grab cancels the whole navigation and puts focus back on the window you came from.
All of these bindings can be changed or switched off in the extension settings, reached through the Extensions application and then PaperWM and Settings. The repository carries the editor for that pane as separate GTK source files, KeybindingsPane.ui, KeybindingsRow.ui and KeybindingsComboRow.ui, alongside prefsKeybinding.js.
Most keybindings start with Super by default. If Super sits somewhere awkward, GNOME Tweaks can swap it: under Keyboard and Mouse, then Additional Layout Options, then Alt/Win key behavior, set Left Alt is swapped with Left Win. Swap it and the bindings that start with Super become easier to reach.
Scrolling the strip has three separate paths depending on hardware. Three finger horizontal trackpad swipes work on Wayland only. A touch screen panel can be swiped. The mouse scroll wheel over the topbar works regardless. The Wayland restriction matters if you are on X11 with a three finger gesture habit: it will not fire.
Per monitor workspaces come from a separate workspace.js module
Each monitor gets its own set of workspaces rather than one workspace list shared across every screen. The implementation is not a stub: workspace.js sits alongside tiling.js, navigator.js and overviewlayout.js in the top level of the repository, and virtTiling.js sits next to them.
The file layout tells you more than a feature list would. grab.js and acceleratorparse.js handle input grabbing and key sequence parsing, minimap.js and topbar.js handle the pieces PaperWM paints on top of the shell, stackoverlay.js handles the column overlay, and scratch.js is a separate scratch space. media/ and resources/ hold bundled assets. stylesheet.css carries the shell styles.
Live alt tab is handled by liveAltTab.js. Alt and Tab still works alongside the directional keys.
Configuration is per user and lives beside the extension. The Makefile lists config/user.js and config/user.css among its release files, and the README says running the extension will automatically install a user config file. winprops.js in the examples directory is the hook for per window properties, and examples/layouts.js and examples/keybindings.js show the other two extension points. preferences for individual windows are edited through winpropsPane.js and WinpropsPane.ui.
make install symlinks the checkout, and refuses to overwrite a packaged copy
Installing from source means linking your working copy into the extension directory. The Makefile resolves the target to $(XDG_DATA_HOME)/gnome-shell/extensions/[email protected], defaulting XDG_DATA_HOME to ${HOME}/.local/share when it is unset, and the install target creates that directory and runs ln -snf against the repository root.
From a checkout on the right branch:
make install # compile schemas and link the checkoutBecause the target is a symlink, edits to your checkout take effect after a Shell restart, with no reinstall step. That is also why the Makefile refuses to run when a real directory already sits at that path: an existing non symlinked installation means the extension came from your package manager or a previous copy, and the install stops with a message telling you to remove it first.
Shell itself must restart before the extension will load. Log out and back in, or on X11 press alt and F2 and enter r. Then enable it through the Extensions application or from the command line:
/usr/bin/gnome-extensions enable [email protected]Removing a source install is the same make target set in reverse:
make uninstallIf the extension refuses to load after an upgrade, the documented fix is to delete stale paperwm@... symlinks from ~/.local/share/gnome-shell/extensions and re-run install.sh. Note that the Makefile falls back to gnome-shell-extension-tool when gnome-extensions is not on PATH, so a system without gnome-extensions uses gnome-shell-extension-tool --disable instead.
Clone the branch that matches your Shell, because nothing backports
Every checkout you install targets a specific range of Shell versions. The default branch covers 45 through 51. GNOME 42 to 44 lives on the gnome-44 branch, 40 and 41 on gnome-40, and 3.28 through 3.38 on gnome-3.38. Those three older branches are marked EOL against the GNOME calendar, and fixes are not backported to them.
A pull request for one of those older branches is accepted only if the submitter can test it and update the related documentation. On an EOL branch you are maintaining your own fix.
Development happens elsewhere. Pull requests are to be based on and submitted to develop, and ones aimed at the shipping branch are not accepted, though the target is retargeted to develop automatically if you get it wrong. The Makefile's default target is described in its own comments as updating compiled files, and install depends on schemas/gschemas.compiled, so a schema change has to be compiled before an install will pick it up. The last push to the repository was on 2026-10-13.
Why the shell version you pick becomes your upgrade ceiling
The failure mode specific to PaperWM is version coupling, and it starts before you install anything. An extension that rewrites window placement inside Shell breaks when Shell changes the internal APIs it was written against. PaperWM answers this by shipping per version branches rather than by isolating itself, so choosing a branch is choosing which Shell versions you can upgrade to.
Pick the default branch and you get GNOME 45 through 51. That is a range, not a guarantee: when a new GNOME release lands, whether an existing PaperWM install works depends on whether the extension has been updated for the Shell internal changes, and the extension distribution page is where you check that before an OS upgrade rather than after.
Pick gnome-44 and you are on GNOME 42 to 44 with no backported fixes. That is not a stale branch you will update soon; those Shell versions are already listed as EOL.
The related risk is thinner. The default branch in the repository is the stable line, while development happens on develop. Cloning without specifying a branch and then assuming you have the newest work is a mistake the Makefile will not catch.
NixOS VM for trying it, and what tiling alternatives actually change
There is a way to see the layout before touching your session. The repository carries default.nix, flake.nix, shell.nix and vm.nix, a lightweight NixOS VM built for trying PaperWM and for development work. With Nix installed:
nix run .\#vmFor GPU acceleration, install NixGL first and choose the wrapper for your host GPU:
nixGLIntel nix run .\#vm -- -device virtio-gpu-gl -display gtk,gl=on
# or nixGLNvidia depending on your host GPUThat is a separate machine, so nothing here proves PaperWM on your hardware, only what the tiling looks like.
PaperWM keeps a single horizontal strip that scrolls, with columns created only when you stack a window under another with Super and I.
Against i3, the difference is the session, not the tiling. i3 is a standalone window manager you start and log into; PaperWM is an extension inside a GNOME session, which keeps the Shell overview, the topbar and the Extensions application, and costs you the ability to run a plain GNOME session without the rewriting. Against niri, the difference is the same one in reverse: niri is a scrollable tiling compositor in its own right, so it gives you the horizontal strip without GNOME, at the price of losing the desktop you had.
The choice is not tiling versus no tiling. It is whether your window strip has to live inside GNOME.
Editorial conclusion
Adopt PaperWM if you already live in GNOME and want a tiling strip without swapping your compositor, and pass on it if you need a session that survives GNOME version bumps untouched, or if you are already on the KDE or macOS side where nothing here applies. Before installing from source, check the branch table against your Shell version, then confirm that make install produced a symlink rather than a real directory, since the install target refuses to overwrite a packaged copy at the same path, and check the extension page for your Shell version before an OS upgrade.
Frequently asked questions
How do I install PaperWM?
Install it from the extensions.gnome.org page for PaperWM, or clone the repository, check out the branch matching your GNOME Shell version and run make install. From source, restart GNOME Shell before enabling it with /usr/bin/gnome-extensions enable [email protected].
How do I use PaperWM?
New windows tile to the right of the active window. Hold Super and use the period and comma keys to move focus right and left, which scrolls the strip and shows the minimap, while Super and Return opens a window of the same type as the active one.
How is PaperWM different from pop-shell?
PaperWM tiles into a single horizontal strip that scrolls sideways and only forms a column when you stack a window under the active one.
How does PaperWM compare with i3?
i3 is a standalone window manager you run as your session, while PaperWM is a GNOME Shell extension that keeps the GNOME session, topbar and overview in place. PaperWM targets GNOME 45 to 51 on its default branch.
What are the alternatives to PaperWM?
The alternatives change the session rather than the tiling. pop-shell keeps GNOME, i3 is a separate tiling window manager, and niri is a scrollable tiling compositor that gives the same horizontal strip without GNOME.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/paperwm-paperwm)Star history chart for your README
[](https://hysenlabs.com/projects/paperwm-paperwm)Was this useful?