Getting started

PaperWM.spoon on macOS: install and configure the basics

PaperWM.spoon is a free, scrollable tiling window manager plugin for Hammerspoon on macOS. To set it up, install Hammerspoon, clone the PaperWM.spoon repository into Hammerspoon's Spoons directory, load and start the Spoon from init.lua, and grant the permissions macOS requests. The commands below follow the project's README, checked on 2026-11-12.

Key facts

  • PaperWM.spoon is a Hammerspoon Spoon, rather than a standalone Mac app.
  • Its README provides a clone command and Lua configuration examples.
  • The README asks users to change two Mission Control settings: disable automatic Space rearrangement and enable separate Spaces for displays.
  • It is a good fit if you want a configurable Lua-based setup; people who prefer to avoid maintaining Hammerspoon configuration may choose a different tool.

Install Hammerspoon first

Get Hammerspoon from its official site, checked on 2026-11-12. Open it once and follow macOS permission prompts. Hammerspoon runs automation scripts, so review what you install and the code you choose to load. The PaperWM.spoon project README describes the plugin and its setup. We have not tested these steps on every macOS version.

PaperWM.spoon's official README, checked on 2026-11-12, gives this installation command:

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

Run it in Terminal. It clones the repository into the Spoons folder used by Hammerspoon. If you use a custom Hammerspoon configuration directory, adjust the destination to match it.

Set the Mission Control options

The README directs you to System Preferences → Desktop & Dock and the Mission Control section. On current macOS, open System Settings → Desktop & Dock, then scroll to Mission Control. Turn off Automatically rearrange Spaces based on most recent use and turn on Displays have separate Spaces. The exact wording and placement can vary by macOS version. The README lists these options as part of its setup.

These are system-wide choices that affect how macOS handles Spaces. Decide whether they fit your setup before changing them. If you use multiple displays, verify that their Space behavior matches what you want.

Load and start the Spoon

Open Hammerspoon's configuration file at ~/.hammerspoon/init.lua. Add the following Lua lines:

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

Save the file. From Hammerspoon's menu bar icon, choose Reload Config. The first line loads the Spoon, the second registers its documented default keybindings, and the third starts managing windows. The project README also shows a SpoonInstall route and sample custom bindings. Start with its defaults before editing keys so you can tell whether the setup loaded.

To stop PaperWM.spoon, call PaperWM:stop() through Hammerspoon's console or configuration. If startup reports a missing Spoon, check that the clone folder is named PaperWM.spoon and sits inside the Spoons directory Hammerspoon uses. Check Hammerspoon's console for Lua errors before changing several settings at once.

Check the bindings and make one change

PaperWM.spoon's README, checked on 2026-11-12, documents defaults for focus with Option–Command–arrows, swap with Option–Command–Shift–arrows, and width cycling with Option–Command–R. It also shows bindings for floating, Spaces, and window sizing. If a shortcut conflicts with another app, edit the Lua table, reload the config, and check Hammerspoon's console if the plugin stops responding.

The Spoon's own configuration can filter applications and adjust window ratios. The README shows window_filter and window_ratios as configuration points. Change only a setting you can identify in the documentation, then test a normal app window and one app you want excluded. The maintainers also note that macOS limits moving windows fully off-screen, so tiled windows at the edges may remain partly visible.

This is a Lua-based toolchain. It suits people who are comfortable reading a config file and want Hammerspoon's flexibility. People who prefer a standalone app and a settings window may find this setup demanding to maintain. The README's setup instructions are the authority for PaperWM.spoon; check the repository before following them because open-source projects can change.

The PaperWM.spoon README says it is “Inspired by PaperWM” and links to the PaperWM project, checked on 2026-11-12. The projects have separate implementations and setup instructions.

We make SlidePane, a macOS app for people who want to configure window layouts without maintaining Lua scripts. It may suit you if you prefer app settings and built-in shortcut controls; PaperWM.spoon is a better fit when you want its Hammerspoon scripting model. See the installation guide for the app setup.

The Niri for Mac article compares another scrolling workflow. The shortcuts guide explains how to review app bindings.

Cite or share this page

Dapols. "PaperWM.spoon on macOS: install and configure the basics." SlidePane, November 18, 2026. https://slidepane.com/en/blog/paperwm-spoon-setup

The link is stable. The citation uses the page's “Last updated” date.