AeroSpace on Mac: Setup, vs yabai, vs Ribbon

AeroSpace is a free, open-source tiling window manager for macOS, modelled on i3. You configure it in one TOML file, it never asks you to turn off SIP, and it switches workspaces with no animation. If you came from i3 or sway on Linux, it's the closest thing the Mac has.

We make a different kind of window manager, Ribbon, so we have a bias. We'll keep it out of the first half of this page. AeroSpace deserves a straight explanation, and a lot of people searching for it should just install it.

What AeroSpace does

• Tree tiling. Each workspace is a tree of containers. A container lays out its children as tiles (side by side) or accordion (overlapping, like i3's stacked mode). Open a window and the focused container splits again.
• Its own workspaces. AeroSpace ignores macOS Spaces. When a workspace is inactive, its windows are moved off-screen into a corner. Its guide gives the reasons: Spaces animate slowly, the animation can't be disabled, and they're hard to script.
• Text config, no GUI. Everything lives in ~/.aerospace.toml. The README says it "will never provide a GUI for configuration."
• A CLI. The aerospace command does everything a binding can, which makes it easy to script.

It's labelled public beta. The README says it "can be used as a daily driver", with breaking changes possible until 1.0. The latest tag on 1 November 2026 was v0.21.3-Beta. The binary runs on macOS 13+.

Installing AeroSpace

brew install --cask nikitabobko/tap/aerospace

1. Open AeroSpace and grant Accessibility in System Settings → Privacy & Security.
2. Copy the default config from the guide to ~/.aerospace.toml. With no file, it uses built-in defaults.
3. Try the default bindings:
   • alt+h/j/k/l to focus
   • alt+shift+h/j/k/l to move
   • alt+1 … alt+9 to switch workspace
   • alt+shift+1 … to send a window to a workspace
4. Run aerospace reload-config after each edit.

The README warns the app isn't notarized. Homebrew handles that for you. A manual download needs the quarantine flag removed.

yabai vs AeroSpace

This pairing gets searched more than any other comparison in the category. Short version:

Choose AeroSpace if you want i3 semantics and refuse to touch SIP. Choose yabai if you want real Spaces and a deeper CLI. We go further into yabai, including the full SIP list, in yabai on Mac.

Where Ribbon is different (it isn't i3)

Ribbon doesn't do trees, modes or workspaces of its own. It's a scrolling window manager. Each display gets a strip of full-height columns that runs past the screen edge. Open a window and it gets its own column, and nothing else shrinks. To reach something off-screen, you scroll the strip.

If AeroSpace annoys you because the fifth window is too narrow to read, that's what Ribbon fixes. If what you love about AeroSpace is i3 itself, Ribbon will feel wrong, and you should stay put.

AeroSpace wins on: price, source, scripting, instant workspace switching, Intel support and older macOS. That's a real list.

Ribbon wins on: readable widths with many windows, trackpad navigation, a settings window, and leaving Mission Control alone.

If you switch from AeroSpace to Ribbon

1. Quit AeroSpace and remove it from login items. Two managers on the same windows cause the jumpy layouts we see most in troubleshooting.
2. Turn off Stage Manager (why).
3. In Ribbon Settings, pick the Vim shortcut style. alt+h/l focus becomes ⌃⌥H/L, and move becomes ⌃⌥⇧H/L. If you want alt on its own like AeroSpace, choose the Option style.
4. Your workspaces become native Spaces. ⌃⌥1–9 now jumps to a column on the current strip.
5. Give it a full day. The first hour of scrolling feels odd to everyone.