PaperWM

PaperWM is a GNOME Shell extension which provides scrollable tiling of windows and per monitor workspaces. It's inspired by paper notebooks and tiling window managers.

While technically an extension it's to a large extent built on top of the Gnome desktop rather than merely extending it.

PaperWM aims to continually support current stable GNOME Shell versions (currently GNOME 47-49). Older versions of PaperWM can generally be installed on older GNOME Shell versions (see Install via Source for more information on targeting an older/EOL Gnome version).

New features and fixes aren't generally backported to older Gnome shell versions. Pull requests for fixes to older PaperWM versions (that run on previous Gnome versions) will be accepted if the submitter can help test and update related documentation.

Have questions or comments? Please ask on our Github Discussions board.

Installation

Install via extensions.gnome.org (recommended)

Install via Source

Clone the repo and check out the branch for the GNOME Shell version you're running:

• 45-49 (currently developed/supported): https://github.com/paperwm/PaperWM/tree/release
• 42-44 (EOL): https://github.com/paperwm/PaperWM/tree/gnome-44
• 40-41 (EOL): https://github.com/paperwm/PaperWM/tree/gnome-40
• 3.28-3.38 (EOL): https://github.com/paperwm/PaperWM/tree/gnome-3.38

then run the make install from the repository. The installer will create a link to the repo in ~/.local/share/gnome-shell/extensions. It will then ask if you want to enable PaperWM.

make install # install, load and enable paperwm

Running the extension will automatically install a user config file as described in User configuration & development.

➡️ You'll need to restart GNOME Shell after installing PaperWM, e.g. logout then login, or restart in place with an alt-F2 and entering r (X11 only).

After logging back in, you can then enable PaperWM via the Extensions application, or by running the following command from the command-line:

/usr/bin/gnome-extensions enable paperwm@paperwm.github.com

if you have run into issues, delete any older paperwm@... symlinks from ~/.local/share/gnome-shell/extensions and re-run the install.sh script.

Uninstall PaperWM (if installed via source)

To uninstall simply run make uninstall.

Try without installing

This repo provides a lightweight VM based on NixOS to try PaperWM and aid with development. You can launch it if Nix is installed on your system using this command:

nix run .\#vm

Alternatively, the VM can also be launched with GPU acceleration, by installing NixGL first:

nixGLIntel nix run .\#vm -- -device virtio-gpu-gl -display gtk,gl=on
# or nixGLNvidia depending on your host GPU

Contributing

Users are encouraged to submit issues and Pull Requests!

➡️ Please ensure pull requests are based off, and submitted to, develop branch.

Pull requests submitted to the release branch will not be accepted (but don't worry, if you accidentally submit a PR to the release branch, the target branch will automatically be changed to develop branch).

Usage

Most functionality is available using a mouse, eg. activating a window at the edge of the monitor by clicking on it. Wayland support gestures (See the Touchpad Gestures section). PaperWM is designed to work work well with keyboard + mouse, trackpads etc.

Most keybindings start with the Super modifier (by default), which is usually the Windows key, or on mac keyboards it's the Command key. It's possible to modify the keyboard layout so that Super is switched with Alt making all the keybindings easier to reach. This can be done through Gnome Tweaks under Keyboard & Mouse ⟶ Additional Layout Options ⟶ Alt/Win key behavior ⟶ Left Alt is swapped with Left Win.

Most keybindings will grab the keyboard while Super is held down, only switching focus when Super is released. Escape will abort the navigation taking you back to the previously active window.

All PaperWM keybinds can be changed (and disabled) via PaperWM extension settings, which can be accessed through Extensions ⟶ PaperWM ⟶ Settings.

Window management and navigation is based around the three following concepts.

Scrollable window tiling

New windows are automatically tiled to the right of the active window (see here for dynamically changing the insertion position of new windows), taking up as much height as possible. SuperReturn will open a new window of the same type as the active window.

Activating a window will ensure it's fully visible, scrolling the tiling if necessary. By default, pressing Super. activates the window to the right. Super, activates the window to the left. On a US keyboard these keys are intuitively marked by < and >, they are also ordered the same way on almost all keyboard layouts. Navigating around windows brings up the minimap as can be seen in the above screenshot. The minimap will stay visible as long as Super is continually being pressed.

Pressing SuperI will move the window to the right below the active window, tiling them vertically in a column. SuperO will do the opposite, pushing the bottom window out of the current column.

You can scroll the tiling by swiping the trackpad horizontally with three fingers (Wayland only), swiping the panel on a touch screen, or using the mouse scroll wheel on the topbar.

AltTab is of course also available.

Default window Keybindings	Can be changed in PaperWM extension settings
SuperReturn or SuperN	Open a new windows (of the current application)
SuperBackspace	Close the active window
Super. or Super,	Switch to the next or previous window
SuperLeft or SuperRight	Activate the window to the left or right
SuperUp or SuperDown	Activate the window above or below
SuperHome or SuperEnd	Activate the first or last window
Not set by default (set in extension settings)	Switch to the [second to eleventh] window
SuperTab or AltTab	Cycle through previously active windows
ShiftSuperTab or ShiftAltTab	Cycle through previously active windows (backward order)
CtrlAltTab	Cycle through previously active scratch windows
ShiftCtrlAltTab	Cycle through previously active scratch windows (backward order)
ShiftSuperC	Switch between window focus modes
ShiftSuperW	Switch between positions for creating/dropping new windows
Not set by default (set in extension settings)	Create/drop windows to the right of current window
Not set by default (set in extension settings)	Create/drop windows to the left of current window
Not set by default (set in extension settings)	Create/drop windows in vertical stack (down)
Not set by default (set in extension settings)	Create/drop windows in vertical stack (up)
Not set by default (set in extension settings)	Create/drop windows at start position
Not set by default (set in extension settings)	Create/drop windows at end position
SuperCtrl, or SuperCtrl.	Move the current window to the left or right
ShiftSuper, or ShiftSuper.	Move the current window to the left or right
SuperCtrlLeft or SuperCtrlRight	Move the current window to the left or right
SuperCtrlUp or SuperCtrlDown	Move the current window up or down
SuperI	Absorb window into the active column
SuperO	Expel the bottom window from vertically tiled windows
ShiftSuperO	Expel the active window from vertically tiled windows
SuperC	Center windows horizontally
ShiftSuperF	Toggle fullscreen
SuperF	Maximize the width of a window
ShiftSuper+	Increment window height (scratch or vertically tiled windows)
ShiftSuper-	Decrement window height (scratch or vertically tiled windows)
Super+	Increment window width
Super-	Decrement window width
SuperR	Resize the window (cycles through useful widths)
SuperAltR	Resize the window (cycles backwards through useful widths)
SuperShiftR	Resize the window (cycles through useful heights)
SuperShiftAltR	Resize the window (cycles backwards through useful heights)
Supert	Take window(s) dropping when finished navigating
Not set by default (set in extension settings)	Activate the window under mouse cursor

The workspace stack & monitors

Pressing SuperAbove_Tab will slide the active workspace down revealing the stack as shown in the above screenshot. You can then flip through the most recently used workspaces with repeated Above_Tab presses while holding Super down. Above_Tab is the key above Tab (` in a US qwerty layout). Like alt-tab Shift is added to move in reverse order:

Pressing SuperPage_Down and SuperPage_Up will slide between workspaces sequentially:

By default SuperPage_Down and SuperPage_Down are bound to the keybindings "Switch to workspace below/above (**ws from current m