Skip to content
Get packs

Guide · Open source

How to use yabai: tiling windows on macOS

Updated · written with AI from the project's own documentation and checked against our catalogue data

yabai is an open-source tiling window manager for macOS that extends the built-in window manager. It arranges open windows into tiled layouts using a binary space partitioning algorithm, and you control it from the command line. This guide explains what you need before installing, how the main pieces fit together, and where to find the configuration and shortcut resources you will need to get a working setup.

yabaiasmvik/yabai · ★ 29.8k · MIT

Quick start

  1. 1Check your macOS version. Confirm you have Big Sur 11.0.0 or later on Intel, or Monterey 12.0.0 or later on Apple Silicon, and that your version is in the README requirements table.
  2. 2Clone the repository. Run git clone https://github.com/asmvik/yabai in your terminal to get the source.
  3. 3Read the install guide. Open the yabai wiki and follow the installation method and uninstall notes that match your setup.
  4. 4Grant Accessibility permission. Launch yabai when prompted, grant Accessibility access, and restart yabai as the README instructs.
  5. 5Enable separate Spaces. Turn on "Displays have separate Spaces" in the Mission Control settings for your macOS version.
  6. 6Start from sample configs. Copy and adapt the files in the examples directory, and check doc/yabai.asciidoc for each setting.
  7. 7Add shortcuts. Bind keys to yabai commands with skhd or another tool of your choice.

Check the requirements before you install

yabai supports Intel Macs on Big Sur 11.0.0 or later, and Apple Silicon Macs on Monterey 12.0.0 or later, according to the README. The README lists newer macOS releases as supported too, so check the requirements table for your exact version.

yabai must be given permission to use the Accessibility API. It will request access on launch, and the application must be restarted after access is granted.

  • Accessibility permission is required.
  • Screen Recording permission is only needed if you want window animations.
  • On macOS 11 and 12, enable "Displays have separate Spaces" in the Mission Control pane.
  • On macOS 13 and later, enable "Displays have separate Spaces" in the Desktop & Dock tab, inside Mission Control.

Get yabai from the repository

The README's install command clones the project from GitHub. The wiki has brief and detailed installation instructions for several methods, and also explains how to uninstall yabai completely. Read those before you build or run anything.

If you build from source or install from HEAD, the README says you must codesign the binary. Without that, it may lose its accessibility and automation privileges when rebuilt or updated.

git clone https://github.com/asmvik/yabai

Start from the sample configuration

Sample configuration files are in the examples directory of the repository. Use them as a starting point, then refer to the documentation (doc/yabai.asciidoc) or the wiki for the details of each setting.

yabai is controlled through its command line interface. Because it is configured by files and terminal commands, expect to read documentation and make small edits rather than use a settings window.

  • Look in the examples directory for sample configs.
  • Read doc/yabai.asciidoc for the full reference.
  • Use the wiki for installation methods and uninstall steps.

Add keyboard shortcuts

yabai does not require a specific tool for shortcuts. The README says you can define keyboard shortcuts with skhd or any other suitable software you prefer. skhd is a separate project by the same author.

Pick one shortcut tool and map keys to yabai commands. Keep your bindings in plain text files so you can change them later.

Know the extra features and their trade-offs

Beyond tiling, the README lists focus-follows-mouse, disabling animations when switching spaces, and creating spaces past the limit of 16 spaces. Some of these depend on optional steps.

System Integrity Protection can be partially disabled so yabai can inject a scripting addition into Dock.app. The README says this enables control of the window server and extra features. It also states that the author makes no recommendation on whether to do this, so weigh the risk yourself.

  • Focus-follows-mouse: moves focus to the window under the pointer.
  • Disable space-switch animations.
  • Create spaces beyond 16.
  • Optional scripting addition, which needs partially disabled SIP.

Avoid known problem setups

The README lists several caveats. Windows that use native macOS tabs, such as Terminal and Finder, do not behave correctly when creating tabs. Avoid creating tabs in those apps, use apps that do not use NSDocument's tab system, or make those windows float using rules.

Disabling the Finder Desktop with a defaults write command breaks focusing of empty spaces. To turn it back on, run: defaults write com.apple.finder CreateDesktop -bool true

  • Set "Automatically rearrange Spaces based on most recent use" to off for commands that rely on space order.
  • On macOS 14 and later, enable "Show Items On Desktop" for reliable display and space focus in multi-display setups.
defaults write com.apple.finder CreateDesktop -bool true

What people use it for

  • Tiling windows automatically so you can focus on content rather than moving windows by hand.
  • Keyboard-driven layouts for people who prefer not to use the mouse.
  • Managing windows, spaces and displays from the command line.
  • Using focus-follows-mouse so the window under the pointer becomes active.
  • Creating more than 16 spaces, as listed in the README.

Frequently asked questions

Is yabai free?

yabai is licensed under the MIT License, a short permissive license that requires only that copyright and license notices are preserved. The source is in the asmvik/yabai repository on GitHub.

What macOS version do I need for yabai?

The README lists Big Sur 11.0.0 or later for Intel Macs and Monterey 12.0.0 or later for Apple Silicon. Newer releases such as Ventura, Sonoma, Sequoia and Tahoe are also listed as supported in the requirements table.

Why does yabai ask for Accessibility permission?

The README says yabai must be given permission to use the Accessibility API and will request it on launch. You must restart yabai after granting access.

Do I need to use the terminal to use yabai?

Yes. The README describes yabai as controlled through a command line interface, so it is not a point-and-click app. Keyboard shortcuts can be added with skhd or another tool.

What are the alternatives to yabai?

The source lists Amethyst, Rectangle, Hammerspoon and Aerospace as comparable projects. Check each one's documentation to see which fits your workflow, since this guide does not compare them in detail.

Why do my windows behave oddly with Terminal or Finder tabs?

The README says windows using native macOS tabs, such as Terminal and Finder, do not behave correctly when creating tabs. Avoid creating tabs in those apps, or make those windows float using rules.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

yabai suits Mac users who are comfortable with a terminal and config files and want keyboard-driven tiling, multi-space control and focus-follows-mouse. If you want a point-and-click tool with no command line, or you cannot grant Accessibility permission, pick a simpler option such as Amethyst, Rectangle, Hammerspoon or Aerospace from the source's comparison list.

Install options & downloads