PaperWM.spoon setup and troubleshooting guide

What PaperWM.spoon is

PaperWM.spoon describes itself as a "tiled scrollable window manager for MacOS". It's modeled on 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.

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), Safari (#72), Microsoft Office (#55), Chromium-based browsers (#159), and native tabs (#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, #139 and #71. First try the README's advice: stack your displays vertically in the arrangement.

Animations feel jittery

See #103, #74 and #108.

Moving windows between Spaces broke

Discussed in #52 and #60. Open as of September 2026: #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 and #165. Open as of September 2026: #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 is a native app built on the same strip model.

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, or Niri vs PaperWM on 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.

FAQ