# PaperWM for Mac: your two real options

Source: https://ribbonformac.com/paperwm-for-mac  
Updated: 2026-10-22

PaperWM itself is a GNOME Shell extension, so it can't run on a Mac. To get its scrolling layout on macOS you have two kinds of choice: **PaperWM.spoon**, a free Lua plugin for Hammerspoon that you configure in a text file, or a **native app** like Ribbon that you set up in a settings window.

## Why there's no real PaperWM for macOS

[PaperWM](https://github.com/paperwm/PaperWM) lives inside GNOME Shell. It relies on GNOME's window manager, Mutter, to draw and place windows. macOS has no GNOME Shell and doesn't let apps take over how windows are drawn. What a Mac app can do is move and resize other apps' windows through the Accessibility API, and that's enough to rebuild the strip.

## Option 1: PaperWM.spoon

[PaperWM.spoon](https://github.com/mogenson/PaperWM.spoon) is a plugin for [Hammerspoon](https://github.com/Hammerspoon/hammerspoon), the free Lua automation tool for macOS. It's inspired by GNOME's PaperWM and copies its main ideas:

- A horizontal strip of columns for each Space and each screen.
- Width cycling through a list of ratios (golden-ratio steps by default).
- "Slurp" a window into a column and "barf" it back out.
- Columns can be shown stacked like an accordion.
- A floating layer, split screen, and multi-screen support.
- An optional trackpad swipe to scroll the strip, off until you set `swipe_fingers`.

It's free, MIT-licensed and actively maintained. Hammerspoon needs macOS 13 or later. You install it by cloning the repo into `~/.hammerspoon/Spoons/` and adding three lines to `init.lua`; the [PaperWM.spoon setup guide](https://ribbonformac.com/paperwm-spoon-setup) has the steps.

Things to know:

- **You'll be editing Lua.** Options like gaps, widths and per-app widths live in `init.lua`. Hammerspoon does nothing until you write a config.
- **The defaults use ⌥⌘.** That clashes with some app shortcuts. ⌥⌘I, for example, also opens the developer tools in Safari and Chrome. You can rebind everything.
- **One default clash.** In the shipped defaults, refresh and "cycle height" are both on ⌥⌘⇧R.
- **Off-screen windows stay partly visible.** macOS won't let a window move fully off-screen, so tiled windows outside the view sit in a thin clickable margin at the edges. The README calls this out.
- **Multiple screens should be stacked vertically** in Display settings so windows don't bleed onto the neighbour.

## Option 2: a native app (Ribbon)

Ribbon is a paid Mac app built for this one layout. Instead of a Lua file, every option has a control in a settings window: gap, centring mode, width presets, focus border, swipe fingers, floating rules. The trackpad swipe is on from the start and moves the strip with your fingers. A Mac Setup page checks for macOS settings that would get in the way, such as Stage Manager or a full-screen swipe on three fingers.

It runs on macOS 13 Ventura and later on Apple silicon (M1 or later), uses native Spaces with one strip per Space and per display, and needs only the Accessibility permission. Its window engine is built on [Paneru](https://github.com/karinushka/paneru), which is MIT-licensed and free if you'd rather use a TOML file and the terminal.

The trade-offs: Ribbon costs $9.99 once for one Mac, it's closed source, and it can't be scripted the way Hammerspoon can. All sales are final with no refunds (see the [terms](https://ribbonformac.com/terms)), so try the strip in the [live demo](https://ribbonformac.com/#demo) first.

## Keys compared

PaperWM on GNOME uses Super. PaperWM.spoon moves that to ⌥⌘. Ribbon uses ⌃⌥.

| Action | PaperWM (GNOME) | PaperWM.spoon | Ribbon |
| --- | --- | --- | --- |
| Focus left / right | Super+Left / Right | <kbd>⌥⌘←</kbd> / <kbd>⌥⌘→</kbd> | <kbd>⌃⌥←</kbd> / <kbd>⌃⌥→</kbd> (or H / L) |
| Move window left / right | Super+Ctrl+Left / Right | <kbd>⌥⌘⇧←</kbd> / <kbd>⌥⌘⇧→</kbd> (swap) | <kbd>⌃⌥⇧←</kbd> / <kbd>⌃⌥⇧→</kbd> |
| First / last window | Super+Home / End | Not in defaults | <kbd>⌃⌥⌘←</kbd> / <kbd>⌃⌥⌘→</kbd> |
| Cycle width | Super+R | <kbd>⌥⌘R</kbd> | <kbd>⌃⌥R</kbd> |
| Full width | Super+F | <kbd>⌥⌘F</kbd> | <kbd>⌃⌥F</kbd> |
| Centre | Super+C | <kbd>⌥⌘C</kbd> | <kbd>⌃⌥C</kbd> |
| Wider / narrower | Super++ / Super+- | Not in defaults | <kbd>⌃⌥=</kbd> / <kbd>⌃⌥-</kbd> |
| Pull into column | Super+I | <kbd>⌥⌘I</kbd> (slurp) | <kbd>⌃⌥]</kbd> or <kbd>⌃⌥[</kbd> |
| Push out of column | Super+O | <kbd>⌥⌘O</kbd> (barf) | <kbd>⌃⌥⇧]</kbd> or <kbd>⌃⌥⇧[</kbd> |
| Cycle height | Super+Shift+R | <kbd>⌥⌘⇧R</kbd> | No presets; <kbd>⌃⌥⇧=</kbd> / <kbd>⌃⌥⇧-</kbd> |
| Float | Scratch layer, Ctrl+Super+Escape | <kbd>⌥⌘⇧Esc</kbd> | <kbd>⌃⌥T</kbd> |
| Tabbed or stacked column | Not listed | <kbd>⌥⌘⇧S</kbd> (stack) | <kbd>⌃⌥⇧T</kbd> (tabs) |
| Switch workspace | Super+PageUp / PageDown | <kbd>⌥⌘1</kbd>–<kbd>⌥⌘9</kbd> | macOS <kbd>⌃←</kbd> / <kbd>⌃→</kbd> |
| Move window to workspace | Ctrl+Super+PageUp / PageDown | <kbd>⌥⌘⇧1</kbd>–<kbd>⌥⌘⇧9</kbd> | No shortcut; Mission Control |

## Pros and cons at a glance

| | PaperWM.spoon | Ribbon |
| --- | --- | --- |
| Price | Free, MIT | $9.99 once, closed source |
| Setup | Install Hammerspoon, clone, write Lua | Install the app, allow Accessibility |
| Settings | `init.lua` | Settings window |
| Scripting | Full Lua through Hammerspoon | `ribbon://` URLs and a CLI |
| Trackpad swipe | Opt-in, configured in Lua | On by default, 3 or 4 fingers |
| Spaces | Native Spaces, a strip each | Native Spaces, a strip each |
| Minimum macOS | 13 (Hammerspoon) | 13 Ventura |
| Support | GitHub issues | Email the developer |

**Choose PaperWM.spoon** if you already use Hammerspoon, like keeping config in dotfiles, or want to script the layout. It's a capable tool and costs nothing.

**Choose Ribbon** if you want the layout working in ten minutes without writing code, and you'd rather adjust it with switches than with Lua.

Other free choices exist too. OmniWM and Nehir follow [niri](https://ribbonformac.com/niri-for-mac) more than PaperWM; [niri vs PaperWM](https://ribbonformac.com/niri-vs-paperwm-mac) explains the difference. For the whole field, see [the best scrolling window managers for Mac](https://ribbonformac.com/best-scrolling-window-managers-for-mac). When you're ready, Ribbon is on the [buy page](https://ribbonformac.com/buy).

## FAQ

### Does PaperWM work on macOS?

No. PaperWM is a GNOME Shell extension and needs GNOME. On a Mac you can use PaperWM.spoon, a Hammerspoon plugin inspired by it, or a native app like Ribbon.

### Is PaperWM.spoon free?

Yes. PaperWM.spoon and Hammerspoon are both free and MIT-licensed. You do need to configure them in Lua.

### Does PaperWM.spoon support trackpad swipes?

Yes, but it's off by default. Set `PaperWM.swipe_fingers` to 2, 3 or 4 in your `init.lua` to turn it on.

### Can I use PaperWM.spoon and Ribbon together?

No. Two window managers moving the same windows fight each other. Stop one before starting the other.

### Do I need to disable SIP for either?

No. Ribbon needs only the Accessibility permission and works with System Integrity Protection on. PaperWM.spoon's install steps don't involve SIP either.

## Keep reading
- [PaperWM.spoon setup](https://ribbonformac.com/paperwm-spoon-setup) — Hammerspoon, init.lua, Mission Control settings, the swipe, and hotkey fixes.
- [Niri vs PaperWM](https://ribbonformac.com/niri-vs-paperwm-mac) — Compositor vs GNOME extension: the real differences, and the Mac options for both.
- [Best scrolling WMs for Mac](https://ribbonformac.com/best-scrolling-window-managers-for-mac) — Ribbon, OmniWM, Nehir, Paneru, PaperWM.spoon and the rest, ranked by situation.
- [Scrolling WMs explained](https://ribbonformac.com/what-is-a-scrolling-window-manager) — The strip, the columns, the moves, and every scrolling WM by operating system.
- [Niri for Mac](https://ribbonformac.com/niri-for-mac) — Niri itself is Linux-only. Five ways to get its scrolling strip on macOS.