PaperWM for Mac: your two real options

Why there's no real PaperWM for macOS

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 is a plugin for 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 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, 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), so try the strip in the live demo first.

Keys compared

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

Pros and cons at a glance

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 more than PaperWM; niri vs PaperWM explains the difference. For the whole field, see the best scrolling window managers for Mac. When you're ready, Ribbon is on the buy page.