PaperWM Save

Tiled scrollable window management for Gnome Shell

Project README


project chat

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.

Can be installed on Gnome Shells from 3.28 to 46 on X11 and wayland.

While PaperWM can be installed on a wide range of Gnome versions, new features aren't generally backported to previous versions. Fixes may be backported on request (please submit a new issue if you've identified a recent fix that should be backported and you can help with testing).

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

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


Install via

Intall it on

Install via Source

Clone the repo and check out the branch supporting the Gnome Shell version you're running.

Then run the script 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.

./ # install, load and enable paperwm

➡️ You will 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 will can then enable PaperWM via the Extensions application, or by running the following command from the command-line:

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

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

Uninstall PaperWM

To uninstall simply run ./

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


Users are enouraged 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 we won't be mad, and will just ask you to change it).


Most functionality is available using a mouse, eg. activating a window at the edge of the monitor by clicking on it. In wayland its possible to navigate with 3-finger swipes on the trackpad. But the primary focus is making an environment which works well with a keyboard.

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 Keybard & MouseAdditional Layout OptionsAlt/Win key behaviorLeft 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.

Adding Ctrl to a keybinding will take the current window with you when navigating.

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

Scrollable window tiling

The window tiling with the minimap shown

New windows are automatically tiled to the right of the active window, 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. 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.

Swiping the trackpad horizontally with three fingers (only available in Wayland) or swiping the panel horizontally on a touch screen will scroll the tiling.

AltTab is of course also available.

PaperWM doesn't handle attached modal dialogs very well, so it's best to turn it off in Gnome Tweaks (under Windows).

Super, or Super. Activate 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
SuperCtrl, or SuperCtrl. 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
Supert Take the window, placing it when finished navigating
SuperTab or AltTab Cycle through the most recently used windows
SuperShiftTab or AltShiftTab Cycle backwards through the most recently used windows
SuperC Center the active window horizontally
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)
SuperF Maximize the width of a window
SuperShiftF Toggle fullscreen
SuperReturn or SuperN Create a new window from the active application
SuperBackspace Close the active window
SuperI Absorb the window to the right into the active column
SuperO Expel the bottom window out to the right

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:

The most recently used workspace stack

Pressing SuperPage_Down and SuperPage_Up will slide between workspaces sequentially:

Sequential workspace navigation

By default SuperPage_Down and SuperPage_Down are bound to the keybindings "Switch to workspace below/above (ws from current monitor)". That means using the keybindings you can select all workspaces that were previously shown on the current monitor and all empty once.

Alternatively you can change these keybindings to "Switch to workspace below/above (ws from all monitors)" in the settings. That way you can switch to all workspaces (that are not currently shown on another monitor). Depending on your workflow this might feel more natural.

The workspace name is shown in the top left corner replacing the Activities button adding a few enhancements. Scrolling on the name will let you browse the workspace stack just like SuperAbove_Tab. Left clicking on the name opens Gnome overview, while right clicking the name lets you access and change the workspace name.

If you prefer to use another workspace indicator (or prefer none at all), you can hide this workspace name element from Gnome topbar by executing the following command from a terminal:

dconf write /org/gnome/shell/extensions/paperwm/show-workspace-indicator false

Swiping down on the trackpad vertically with three fingers will initiate the workspace stack, and then allow you navigate the workspace stack with 3-finger vertical swipes (only available in Wayland). See the Touchpad Gestures section for more information on gesture support in PaperWM.

There's a single scrollable tiling per workspace. Adding another monitor simply makes it possible to have another workspace visible. The workspace stack is shared among all the monitors, windows being resized vertically as necessary when workspace is displayed on another monitor.

PaperWM currently works best using the workspaces span monitors preference, this can be turned on with Gnome Tweaks under Workspaces. If you want to use workspaces only on primary you need to place the secondary monitor either below or above the primary (with the best result having it below).

Workspace Keybindings
SuperAbove_Tab Cycle through the most recently used workspaces
SuperShiftAbove_Tab Cycle backwards through the most recently used workspaces
SuperCtrlAbove_Tab Cycle through the most recently used, taking the active window with you
SuperCtrlShiftAbove_Tab Cycle backwards through the most recently used, taking the active window with you
SuperPage_Down/Page_Up Cycle sequentially through workspaces (from current monitor only)
no default keybinding Cycle sequentially through workspaces (from all monitors)
SuperCtrlPage_Down/Page_Up Cycle sequentially through workspaces, taking the active window with you
Monitor Keybindings
SuperShiftArrow_key Select neighbouring monitor
SuperShiftCtrlArrow_key Move active window to neighbouring monitor

Scratch layer

The floating scratch layer, with the alt tab menu open

The scratch layer is an escape hatch to a familiar floating layout. This layer is intended to store windows that are globally useful like chat applications and in general serve as the kitchen sink. When the scratch layer is active it will float above the tiled windows, when hidden the windows will be minimized.

Pressing SuperEscape toggles between showing and hiding the windows in the scratch layer. Activating windows in the scratch layer is done using SuperTab, the floating windows having priority in the list while active. When the tiling is active SuperShiftTab selects the most recently used scratch window.

SuperCtrlEscape will move a tiled window into the scratch layer or alternatively tile an already floating window. This functionality can also be accessed through the window context menu (AltSpace).

SuperEscape Toggle between showing and hiding the most recent scratch window
SuperShiftEscape Toggle between showing and hiding the scratch windows
SuperCtrlEscape Toggle between floating and tiling the current window
SuperTab Cycle through the most recently used scratch windows
SuperH Minimize the current window

User configuration & development

⚠️ Gnome 45 removed the ability to add external module files to the search path of extensions. Hence, modifications to PaperWM via user.js is not currently available in Gnome 45.

user.js functionality is still available in PaperWM for previous Gnome shell versions.

A default user configuration, user.js, is created in ~/.config/paperwm/ with three functions init, enable and disable. init will run only once on startup, enable and disable will be run whenever extensions are being told to disable and enable themselves.

You can also supply a custom user.css in ~/.config/paperwm/. This user stylesheet can override the default styles of paperwm (e.g. from ~/.local/share/gnome-shell/extensions/[email protected]/user.css or /usr/share/gnome-shell/extensions/[email protected]/user.css), gnome or even other extensions. The same rules as for CSS in the browser apply (i.e. CSS rules are additive).

You can reload the user.css by disabling (turning off) PaperWM and then re-enabling PaperWM (turning on), e.g via Extensions app, or by running Main.loadTheme() in looking glass (i.e. AltF2 lg Return). Note that the latter approach will reload all other .css files (e.g. from other extensions) and user.css needs to already be loaded for this to work. So after initially creating the file you'll need to disable then enable PaperWM (or restart Gnome).

We also made an emacs package, gnome-shell-mode, to make hacking on the config and writing extensions a more pleasant experience. To support this out of the box we also install a metadata.json so gnome-shell-mode will pick up the correct file context, giving you completion and interactive evaluation ala. looking glass straight in emacs.

Pressing SuperInsert will assign the active window to a global variable metaWindow, its window actor to actor, its workspace to workspace and its PaperWM style workspace to space. This makes it easy to inspect state and test things out.

Using PaperWM extension settings (UI) to modify settings

PaperWM provides an extension settings UI to modify many of PaperWM's more prevalent settings. This is available in the gnome-extensions application.

Note: not all PaperWM user-configurable settings are available in the settings UI.

Using dconf-editor to modify settings

You can use dconf-editor to view and modify all PaperWM user settings. You can view all settings by executing the following command from a terminal:

GSETTINGS_SCHEMA_DIR=$HOME/.local/share/gnome-shell/extensions/[email protected]/schemas dconf-editor /org/gnome/shell/extensions/paperwm/

PaperWM user-configurable settings not available in settings UI

Below is a list of user-configurable settings that are not exposed in the PaperWM settings UI. These can be modified via dconf-editor.

Note: experimental, incomplete or deprecated settings may not be listed below.

Click to expand and see user-configurable properties

Setting Description Input Type Default value
default‑background Sets the (default) background used for PaperWM workspaces. If set will use this background instead of colors defined in workspace-colors. absolute path empty

Note: you can override this for individual workspaces in the settings UI.


dconf write /org/gnome/shell/extensions/paperwm/default-background '"/home/user/Wallpaper/mars-sunset-2k.jpg"'
Setting Description Input Type Default value
workspace‑colors Sets the workspace background color palette. String array of colors ['#314E6C', '#565248', '#445632', '#663822', '#494066', '#826647', '#4B6983', '#807D74', '#5D7555', '#884631', '#625B81', '#B39169', '#7590AE', '#BAB5AB', '#83A67F', '#C1665A', '#887FA3', '#E0C39E']

Setting window specific properties

It's possible to set window properties using simple rules that will be applied when placing new windows. Properties can applied to windows identified by their wm_class or title. The following properties are currently supported:

Property Input type Input example Description
scratch_layer Boolean true, false if true window will be placed on the scratch layer.
preferredWidth String value with % or px unit "50%", "450px" resizes the window width to the preferred width when it's created. Note1: property not applicable to windows on scratch layer.

Window properties can be added using the Winprops tab of the PaperWM extension settings:

The wm_class or title of a window can be found by using looking glass: AltF2 lg Return Go to the "Windows" section at the top right and find the window. X11 users can also use the xprop command line tool (title is referred as WM_NAME in xprop). The match of wm_class and title are with an OR condition; and in addition to a plain string matching, a constructed RegExp() can be used to utilise regex matching. For example, e.g. /.*terminal.*/i would match on any value that contains the word "terminal" (case-insensitive).

Setting a default window property rule

You can use the functionality defined in the setting window specific properities section to define a default window property rule that will be applied to all windows NOT matched by a more specific window property rule.

You do this by using the special "match all" operator * as an input for wm_class or title. The below image shows setting a default Preferred width value of 50%.

Setting default window property rule

This special operator is at a lower precedence, so more specific properties that match a window will always take precedence and be applied.

New Window Handlers

⚠️ Gnome 45 removed the ability to add external module files to the search path of extensions. Hence, the below user.js functionality is not currently available in Gnome 45.

If opening a new application window with SuperReturn isn't doing exactly what you want, you can create custom functions to suit your needs. For example, you might want new emacs windows to open the current buffer by default, or have new terminals inherit the current directory. To implement this, you can modify user.js as below (see User configuration & development section):

// -*- mode: gnome-shell -*-
const Extension = imports.misc.extensionUtils.getCurrentExtension();
const App =;

function enable() {
    App.customHandlers['emacs.desktop'] =
        () => imports.misc.util.spawn(['emacsclient', '--eval', '(make-frame)']);
    App.customHandlers['org.gnome.Terminal.desktop'] =
        (metaWindow, app) => app.action_group.activate_action(
          new"(ss)", ["window", "current"]));

The app id of a window can be looked up like this:

let Shell =;
let Tracker = Shell.WindowTracker.get_default();
let app = Tracker.get_window_app(metaWindow);

Available application actions can be listed like this:



Due to limitations in the mutter keybinding API we need to steal some built in Gnome Shell actions by default. Eg. the builtin action switch-group with the default SuperAbove_Tab keybinding is overridden to cycle through recently used workspaces. If an overridden action has several keybindings they will unfortunately all activate the override, so for instance because AltAbove_Tab is also bound to switch-group it will be overridden by default. If you want to avoid this, eg. you want AltTab and AltAbove_Tab to use the builtin behavior simply remove the conflicts (ie. SuperTab and SuperAbove_Tab and their Shift variants) from /org/gnome/desktop/wm/keybindings/switch-group (no restarts required).

User defined keybindings

⚠️ Gnome 45 removed the ability to add external module files to the search path of extensions. Hence, the below user.js and examples/keybindings.js functionality is not currently available in Gnome 45.

Extension.imports.keybindings.bindkey(keystr, name, handler, options)

Option Values Meaning
activeInNavigator true, false The keybinding is active when the minimap/navigator is open
opensMinimap true, false The minimap will open when the keybinding is invoked
let Keybindings = Extension.imports.keybindings;
Keybindings.bindkey("<Super>j", "my-favorite-width",
                    (metaWindow) => {
                        let f = metaWindow.get_frame_rect();
                        metaWindow.move_resize_frame(true, f.x, f.y, 500, f.h);
                    { activeInNavigator: true });

See examples/keybindings.js for more examples.

Touchpad Gestures

PaperWM implements the following touchpad gestures by default:

Gesture Action
three-finger swipe up Gnome Overview #setting-window-specific-properties
three-finger swipe down PaperWM workspace stack view (see here)
three-finger swipe left/right Moves tiling viewport (windows) left / right

PaperWM touchpad gesture behaviour can be modified via the General tab in PaperWM settings:

Touchpad gesture settings

Window Position Bar (colored bar segment in Top Bar)

#476 added a coloured window position bar to the Gnome Top Bar. This allows users to visually identify the current selected window position of the scrollable viewport in the current workspace. This is demonstrated in the following video:

The window position bar can be disabled from PaperWM extension settings:

Window indicator bar

You can style both the coloured position bar and the dimmed "position bar backdrop" by overriding the paperwm-window-position-bar and paperwm-window-position-bar-backdrop CSS classes respectively (see user.css in User configuration & development section for more information). The paperwm-window-position-bar will also inherit the selection color (same as window borders) from tile-preview.

Note: PaperWM overrides the default Gnome Top Bar style to be completely transparent so that the dimmed window-position-bar-backdrop and window-position-bar elements are visible.

Window Focus Mode

#482 added the concept of window focus modes to PaperWM. A focus mode controls how windows are "focused". For example, the CENTER focus mode causes all windows to be centered horizontally on selection, whereas the DEFAULT focus mode is the traditional PaperWM behaviour.

Focus modes can be toggled by user-settable keybinding (default is Super+Shift+c), or by clicking the new focus-mode button in the topbar:

Focus mode button

Setting the default focus mode

The default focus mode is the standard PaperWM focus mode (i.e. not centered). This can be changed according to preference by changing the Default focus mode setting PaperWM settings.

Default focus mode

Note: changing this setting during a PaperWM session will set all spaces to the new default focus mode.

Hiding the focus mode icon

Users may also prefer to hide the focus mode icon. You can do so by executing the following command in a terminal:

dconf write /org/gnome/shell/extensions/paperwm/show-focus-mode-icon false

Gnome TopBar opacity / styling

PaperWM by default changes the opacity of the Gnome TopBar. This styling is used for certain PaperWM features. However, this styling may conflict with the TopBar styling of other extensions (that you may prefer have style the TopBar instead).

Users can disable PaperWM's ability to change TopBar styling from PaperWM settings:

Enable TopBar Styling

Note: several PaperWM specific features are dependent on changing the Gnome TopBar to function correctly. If you choose to disable PaperWM's ability to change the TopBar styles (with the setting above), you may also want to disable the Window Position Bar.

Fixed Window Size

See the Winprops section for a way to set the default width of windows identified by their wm_class window property.

Currently it is not possible to have a default fixed window height. Please check the following issues for progress / info:

There's a few Gnome Shell settings which works poorly with PaperWM. Namely

  • workspaces-only-on-primary: Multi monitor support require workspaces spanning all monitors
  • edge-tiling: We don't support the native half tiled windows
  • attach-modal-dialogs: Attached modal dialogs can cause visual glitching

PaperWM manages these settings (disables them) during runtime. It will then restore these settings to their prior values when PaperWM is disabled.

These extensions are good complements to PaperWM:

Incompatible extensions

In most cases it should be enough to disable these extensions.

  • DING (Desktop Icons NG) (shipped by default with Ubuntu) or similar extensions that add desktop icons. Creates invisible windows and does not properly show icons. See #784, #266
  • Fedoras builtin desktop watermark (shipped with Fedora) See #706
  • Rounded Window Corners or similar extensions that change the window shape. See #763, #431
  • Space Bar or similar extensions that modify workspace names etc. See #720
  • Dash to Panel or similar panels. Works in some configurations and in some not. Is incompatible with PaperWMs window position bar. See #170, #199, #646, #382, #166, #258

See issues tagged with the extension-conflict label for current and closed issues related to extension conflicts.

In general extensions that do one of the following are problematic when used together with PaperWM (although they might partially work):

  • Modify the desktop
  • Modify window "shapes" (e.g. rounded corners)
  • Modify workspaces
  • Modify touch gestures

PaperWM will attempt to disable keybindings of some known extensions if they clash. E.g. the Ubuntu Tiling Assistant from Ubuntu 23.10.

Prior work

A similar idea was apparently tried out a while back: 10/GUI

Open Source Agenda is not affiliated with "PaperWM" Project. README Source: paperwm/PaperWM
Open Issues
Last Commit
2 weeks ago

Open Source Agenda Badge

Open Source Agenda Rating