How to use AeroSpace Mac: install it with Homebrew, allow Accessibility, then use the default keys. You do not need a config file on day one. You do not turn off System Integrity Protection.
What the app is, and who should skip it, is in AeroSpace on Mac.
Install
You need macOS 13 or later. Quit any other window manager first, and turn Stage Manager off. Two apps that both move windows will fight.
- Install Homebrew if you do not have it.
- Run:
brew install --cask nikitabobko/tap/aerospace
- Open AeroSpace. The app is not notarized. The cask handles that. A zip from the releases page may need a right-click → Open, or
xattr -d com.apple.quarantine /Applications/AeroSpace.app. - Allow it in System Settings → Privacy & Security → Accessibility. If windows do not tile, toggle the permission off and on, then reopen the app.
AeroSpace does not start at login until you set start-at-login = true or add it to Login Items.
Day-one keys
Option is the modifier. The config calls it alt.
| What you want | Keys |
|---|---|
| Focus left, down, up, right | ⌥H, ⌥J, ⌥K, ⌥L |
| Move the window | ⌥⇧H, ⌥⇧J, ⌥⇧K, ⌥⇧L |
| Resize | ⌥Minus, ⌥Equal |
| Side by side, or stacked | Option-/ |
| Workspace 1 to 9 | ⌥1 through ⌥9 |
| Send the window to a workspace | ⌥⇧ and the number |
| Back to the last workspace | ⌥⇥ |
| Service mode | ⌥⇧-; |
⌥F is workspace F, not full screen. In service mode, Escape returns to the normal keys, R resets the layout, and F floats the focused window. Backspace closes every window but the current one.
Workspaces
Press ⌥1 and open two apps. They tile. Press ⌥2. The screen clears, with no Spaces animation. Press ⌥1 to come back. Press ⌥⇧2 to send the focused window to workspace 2 without following it.
These are not macOS desktops. Mission Control will not show nine tidy Spaces. On more than one monitor, leave a free bottom corner on each screen in System Settings → Displays → Arrange, or hidden windows show up on the wrong display.
The config file
With no file, you are on the built-in defaults. Do not create an empty file. A config replaces the key list.
When you want to change something:
- Copy the default config from section 2.3 of the guide into
~/.aerospace.toml. The other path is~/.config/aerospace/aerospace.toml. Use one, not both. - Change one line.
- Run
aerospace reload-config. Saving the file does nothing until you turn onauto-reload-configand reload once.
If a key does nothing
Quit skhd, and check Karabiner and Raycast. They listen for the same kind of chord. Focus is H, J, K and L, not the arrow keys. If every key is dead, you may be in service mode. Press Escape. If that fails, rename ~/.aerospace.toml and reload. The defaults come back.
If tiles get too narrow, use fewer windows per workspace. A scrolling strip is a different app. Ribbon vs AeroSpace is that comparison. AeroSpace vs yabai is the comparison if you want another tiler.