# PaperWM.spoon setup and troubleshooting guide

Source: https://chainyourmac.com/paperwm-spoon-setup  
Updated: 2026-09-18 · Author: Ahmed Gagan (maker of ChainYourMac)

PaperWM.spoon is a free, actively maintained Hammerspoon Spoon that brings PaperWM-style scrolling tiling to macOS. **Here's how to install it properly and fix it when it misbehaves.**

> **tl;dr:** To install [PaperWM.spoon](https://github.com/mogenson/PaperWM.spoon): install Hammerspoon and grant it Accessibility, clone the repo into `~/.hammerspoon/Spoons/PaperWM.spoon`, set two Mission Control options (uncheck "Automatically rearrange Spaces based on most recent use", check "Displays have separate Spaces"), and add three lines to `init.lua`. It's free, MIT-licensed and actively maintained. If it misbehaves, the fix is usually one of those steps, or a known issue with a specific app or macOS version, listed below.

## What PaperWM.spoon is

PaperWM.spoon describes itself as a "tiled scrollable window manager for MacOS". It's modeled on [PaperWM](https://github.com/paperwm/PaperWM), the GNOME Shell extension (Linux only): windows sit side by side on a horizontal strip and you scroll through them instead of cramming them into a grid. If the idea is new, start with [what a scrolling window manager is](https://chainyourmac.com/what-is-a-scrolling-window-manager).

It isn't a standalone app. It's a *Spoon*, a Lua plugin for Hammerspoon, the macOS automation tool. As of September 2026 it has about 1,760 stars, an MIT license, and its last commit landed on 2026-09-03. It doesn't publish GitHub releases.

## What you need

- **Hammerspoon**, installed and running.
- **Accessibility permission for Hammerspoon.** Every window manager on macOS needs it to move windows. Grant it in System Settings → Privacy & Security → Accessibility.
- **git**, to clone the Spoon (or download the repo by hand).

No SIP changes are required.

## Install, step by step

### 1. Clone the Spoon

This is the command from the README:

`git clone https://github.com/mogenson/PaperWM.spoon ~/.hammerspoon/Spoons/PaperWM.spoon`

To update later, run `git pull` inside that folder and reload your Hammerspoon config.

### 2. Change two Mission Control settings

Open System Settings → Desktop & Dock and scroll to Mission Control:

- **Uncheck** "Automatically rearrange Spaces based on most recent use".
- **Check** "Displays have separate Spaces".

Skipping these is one of the easiest ways to end up with a setup that half-works.

### 3. Load it in init.lua

Add this to `~/.hammerspoon/init.lua`:

`PaperWM = hs.loadSpoon("PaperWM") PaperWM:bindHotkeys(PaperWM.default_hotkeys) PaperWM:start()`

Reload the Hammerspoon config. `PaperWM.default_hotkeys` is the Spoon's built-in keymap; check the README for the current bindings before you change them.

### Alternative: SpoonInstall

If you manage Spoons with SpoonInstall, point it at the PaperWM.spoon repo. Since the project doesn't publish GitHub releases, SpoonInstall uses its `release` branch. The README has the details.

### 4. Optional extras

Built in: trackpad swipe scrolling (set with `swipe_fingers`), moving windows with mouse drag/lift, and scrolling with the mouse wheel. The README also mentions companion Spoons: **WarpMouse**, **ActiveSpace**, **Swipe** and **FocusMode**.

## Known limitations (from the README)

- **Off-screen windows show at the edges.** macOS won't let windows go fully off screen, so hidden windows sit in a visible margin at the left and right edges. ChainYourMac runs into the same macOS rule.
- **Dragging windows between Spaces or screens is hard to detect.** Use the `move_window_N` actions instead of dragging.
- **Multiple monitors:** arrange your screens vertically in Display settings so windows parked off screen don't bleed onto the other monitor.

## Troubleshooting: the problems people hit most

These are the recurring themes in the project's GitHub issues. Check the linked threads for the current status and any workarounds.

### Nothing happens at all

1. Confirm Hammerspoon is running and has Accessibility permission.
2. Open the Hammerspoon Console and look for a Lua error when you reload.
3. Make sure the folder is named exactly `PaperWM.spoon` inside `~/.hammerspoon/Spoons/`.
4. Double-check both Mission Control settings above.

### Some apps' windows aren't tiled, or tile wrong

Specific apps come up again and again: Finder ([#126](https://github.com/mogenson/PaperWM.spoon/issues/126)), Safari ([#72](https://github.com/mogenson/PaperWM.spoon/issues/72)), Microsoft Office ([#55](https://github.com/mogenson/PaperWM.spoon/issues/55)), Chromium-based browsers ([#159](https://github.com/mogenson/PaperWM.spoon/issues/159)), and native tabs ([#39](https://github.com/mogenson/PaperWM.spoon/issues/39)). If an app misbehaves, search the issues for its name before debugging your config.

### Focus jumps or flickers across monitors

Multi-monitor focus and flicker problems are tracked in [#14](https://github.com/mogenson/PaperWM.spoon/issues/14), [#139](https://github.com/mogenson/PaperWM.spoon/issues/139) and [#71](https://github.com/mogenson/PaperWM.spoon/issues/71). First try the README's advice: stack your displays vertically in the arrangement.

### Animations feel jittery

See [#103](https://github.com/mogenson/PaperWM.spoon/issues/103), [#74](https://github.com/mogenson/PaperWM.spoon/issues/74) and [#108](https://github.com/mogenson/PaperWM.spoon/issues/108).

### Moving windows between Spaces broke

Discussed in [#52](https://github.com/mogenson/PaperWM.spoon/issues/52) and [#60](https://github.com/mogenson/PaperWM.spoon/issues/60). **Open as of September 2026:** [#173](https://github.com/mogenson/PaperWM.spoon/issues/173), macOS 27 breaks `moveWindowToSpace`. If you're on macOS 27, expect Space moves not to work until that's resolved.

### Layout is lost after sleep, closing a window, or full screen

See [#117](https://github.com/mogenson/PaperWM.spoon/issues/117) and [#165](https://github.com/mogenson/PaperWM.spoon/issues/165). **Open as of September 2026:** [#133](https://github.com/mogenson/PaperWM.spoon/issues/133).

### Before you open a new issue

The maintainer and other users can help much faster with a good report. Include:

- your macOS version and how many displays you use (and how they're arranged);
- the app whose windows misbehave, and whether it uses native tabs;
- any error from the Hammerspoon Console after a config reload;
- whether the problem still happens after a `git pull` of the latest Spoon.

Search the existing issues first: most problems above already have a thread, and adding details there helps more than a duplicate.

## PaperWM.spoon vs a native app

PaperWM.spoon is a good tool, and if you already live in Hammerspoon, it's the natural choice. If you'd rather not maintain a Lua setup, [ChainYourMac](https://chainyourmac.com/) is a native app built on the same strip model.

|  | PaperWM.spoon | ChainYourMac |
|---|---|---|
| Price | Free, MIT | $9.99 one time, lifetime license |
| Runs as | Hammerspoon Spoon (Lua) | Native app (SwiftUI + Rust engine) |
| Configuration | init.lua | Settings window; changes apply instantly |
| Shortcuts | Lua hotkey table | Shortcut recorder, several per action |
| Trackpad | Swipe scrolling | 3- or 4-finger swipe that follows your fingers |
| Stacks / tabs in a column | See README | Stacks and tabbed columns |
| Off-screen windows | Visible margin at left/right edges | Small tab in a bottom corner (tuckable) |
| Source | Open source | Closed source |
| Requirements | Hammerspoon | macOS 13+, Apple silicon |

ChainYourMac also restores your column order, stacks and tabs after a restart, shows a minimap while you navigate, and brings every off-screen window back when you quit. Longer comparison: [PaperWM for Mac](https://chainyourmac.com/paperwm-for-mac), or [Niri vs PaperWM on Mac](https://chainyourmac.com/niri-vs-paperwm-mac).

## Who should use what

### Use PaperWM.spoon if…

- you already use Hammerspoon and enjoy scripting your setup in Lua;
- you want free and open source.

### Use ChainYourMac if…

- you'd rather set things up in a settings window than maintain `init.lua`;
- you want stacks, tabbed columns, a minimap and session restore out of the box;
- you're on an Apple silicon Mac with macOS 13 Ventura or later.

**Like the strip, not the Lua?** ChainYourMac is the same scrolling workflow as a native Mac app, set up in a settings window instead of init.lua. Price and checkout: https://chainyourmac.com/#pricing (one-time purchase, lifetime license; macOS 13+ on Apple silicon).

## FAQ

### How do I install PaperWM.spoon?

Install Hammerspoon and give it Accessibility permission, then clone the repo into `~/.hammerspoon/Spoons/PaperWM.spoon`. In System Settings → Desktop & Dock → Mission Control, uncheck "Automatically rearrange Spaces based on most recent use" and check "Displays have separate Spaces". Finally load it in `~/.hammerspoon/init.lua` with `hs.loadSpoon("PaperWM")`, bind the default hotkeys and call `PaperWM:start()`.

### Why is PaperWM.spoon not working?

The most common causes are Hammerspoon lacking Accessibility permission, the two Mission Control settings not being set, or an error in `init.lua` (check the Hammerspoon Console). Beyond that, some apps' windows aren't tracked correctly and some macOS versions break Spaces moves; the [GitHub issues](https://github.com/mogenson/PaperWM.spoon/issues) are the place to check.

### Does PaperWM.spoon need SIP disabled?

No. It runs as a Hammerspoon Spoon using the permissions Hammerspoon already has. No SIP changes are needed.

### Is PaperWM.spoon still maintained?

Yes. As of September 2026 the last commit was on 2026-09-03 and the repo has about 1,760 stars. It doesn't publish GitHub releases; SpoonInstall uses its `release` branch.

### Does PaperWM.spoon support trackpad scrolling?

Yes. It has built-in trackpad swipe scrolling (configured with `swipe_fingers`), plus mouse drag/lift and mouse-wheel scrolling. See the README for the exact options.

### Is there a PaperWM for Mac that doesn't need Hammerspoon?

[ChainYourMac](https://chainyourmac.com/) is a native app with the same scrolling model and a settings window instead of Lua. It's paid and needs an Apple silicon Mac. Comparison: [PaperWM for Mac](https://chainyourmac.com/paperwm-for-mac).

## Related

- [PaperWM for Mac](https://chainyourmac.com/paperwm-for-mac) — The GNOME original, the Hammerspoon port, and the native option.
- [Niri vs PaperWM](https://chainyourmac.com/niri-vs-paperwm-mac) — The two Linux originals compared — and what runs on macOS.
- [Best scrolling window managers for Mac](https://chainyourmac.com/best-scrolling-window-managers-for-mac) — Every option in 2026, ranked honestly — free ones included.
- [Scrolling window managers, explained](https://chainyourmac.com/what-is-a-scrolling-window-manager) — The strip model, and how scrolling differs from tiling.