Skip to content
Åsmund Vikane edited this page Sep 26, 2024 · 55 revisions

yabai

Tiling window management native to the Mac.

license documentation changelog version

What is yabai?

yabai is a tiling window manager for macOS Big Sur 11.0.0+, Monterey 12.0.0+, Ventura 13.0.0+, Sonoma 14.0.0+, and Sequoia 15.0.

It automatically modifies your window layout using a binary space partitioning algorithm to allow you to focus on the content of your windows without distractions.

A flexible and easy-to-grok command line interface allows you to control and query windows, spaces and displays to enable powerful integration with tools like ↗ skhd to allow you to work more efficiently with macOS. Create custom keybindings to control windows, spaces and displays in practically no time and get your hands off the mouse and trackpad and back onto the keyboard where actual work gets done.

Installation requirements

Please read the below requirements and recommendations carefully. Make sure you fulfill all requirements before filing an issue.

Requirement Note
Operating System Intel x86-64 Big Sur 11.0.0+, Monterey 12.0.0+, Ventura 13.0.0+, Sonoma 14.0.0+, and Sequoia 15.0 is supported.
Operating System Apple Silicon Monterey 12.0.0+, Ventura 13.0.0+, Sonoma 14.0.0+, and Sequoia 15.0 is supported.
Accessibility API yabai must be given permission to utilize the Accessibility API and will request access upon launch. The application must be restarted after access has been granted.
Screen Recording yabai must be given Screen Recording permission if and only if you want to enable window animations, and will request access when necessary. The application must be restarted after access has been granted.
System Preferences (macOS 11.x, 12.x) In the Mission Control pane, the setting "Displays have separate Spaces" must be enabled.
System Settings (macOS 13.x, 14.x, 15.x) In the Desktop & Dock tab, inside the Mission Control pane, the setting "Displays have separate Spaces" must be enabled.

Please also take note of the following caveats.

Caveat Note
System Integrity Protection (Optional) System Integrity Protection can be (partially) disabled for yabai to inject a scripting addition into Dock.app for controlling windows with functions that require elevated privileges. This enables control of the window server, which is the sole owner of all window connections, and enables additional features of yabai.
Code Signing When building from source (or installing from HEAD), it is necessary to codesign the binary so it retains its accessibility and automation privileges when updated or rebuilt.
Finder Desktop Some people disable the Finder Desktop window using an undocumented defaults write command. This breaks focusing of empty spaces and should be avoided when using yabai. To re-activate the Finder Desktop, run: defaults write com.apple.finder CreateDesktop -bool true
NSDocument-based Applications Windows that utilize native macOS tabs such as Terminal and Finder, do not behave correctly when creating tabs. Avoid creating tabs in these applications, consider alternatives that do not use NSDocument's tab system, or make these windows float using rules.
System Preferences (macOS 11.x, 12.x) In the Mission Control pane, the setting "Automatically rearrange Spaces based on most recent use" should be disabled for commands that rely on the ordering of spaces to work reliably.
System Settings (macOS 13.x, 14.x, 15.x) In the Desktop & Dock tab, inside the Mission Control pane, the setting "Automatically rearrange Spaces based on most recent use" should be disabled for commands that rely on the ordering of spaces to work reliably.
System Settings (macOS 14.x, 15.x) In the Desktop & Dock tab, inside the Desktop & Stage Manager pane, the setting "Show Items On Desktop" should be enabled for display and space focus commands to work reliably in multi-display configurations.
System Settings (macOS 14.x, 15.x) In the Desktop & Dock tab, inside the Desktop & Stage Manager pane, the setting "Click wallpaper to reveal Desktop" should be set to "Only in Stage Manager" for display and space focus commands to work reliably.

Quickstart guide

yabai can be installed via Homebrew from a custom tap. It does, however, require you to partially disable System Integrity Protection ("rootless"), because it controls windows by acting through Dock.app — which is the sole owner of the main connection to the window server.

  1. Optional: Partially disable System Integrity Protection (required for many advanced features)
  2. Install yabai and configure macOS to allow it to run
  3. Configure yabai to your liking
  4. Optional: Integrate yabai with other software like ↗ skhd for keyboard shortcuts or ↗ Übersicht for desktop widgets

You can find detailed instructions on every step of the quickstart guide in this wiki. The sidebar to the right (bottom for mobile devices) has a sorted list of pages with links to individual chapters.

Comparison with other window managers

NOTE: This feature comparison table is far from complete. Please contribute. It's mostly a placeholder in its current state.

yabai ↗ Amethyst
General
Supported macOS versions 11.0–15.0 10.15–15.0
Works with SIP enabled ✓*
Integrate with 3rd party tools Signals, Rules and Commands
Windows
Modify window properties
Spaces
Create and destroy spaces
Move spaces
Displays
Support multiple displays ✓*

* partially

Clone this wiki locally