yabai: A Tiling Window Manager for macOS Built on Binary Space Partitioning

What yabai Actually Solves on macOS

macOS ships with a window manager that is almost entirely manual. You drag windows, you resize them by their corners, and Mission Control gives you spaces that are capped and reordered by recency. yabai is designed as an extension to that built-in manager rather than a replacement for it. The README describes the primary function as tiling window management: the layout is modified automatically using a binary space partitioning algorithm, so windows fill the screen without you placing them.

The audience is narrow and specific. This is a tool for people who already work from a keyboard, who are comfortable editing a configuration file, and who treat their window layout as something to be scripted rather than dragged. The README points at skhd, or any other suitable software, for defining keyboard shortcuts, which tells you the project expects you to bring your own keybinding layer. If you want a window manager that works immediately after a double click on a disk image, this is not that.

The secondary features are worth naming because they are the reason some people tolerate the setup cost: focus-follows-mouse, disabling animations for switching spaces, and creating spaces past the limit of 16 spaces. That last one is a direct workaround for a macOS constraint, not a feature yabai invented for its own sake.

Binary Space Partitioning as the Layout Engine

The mechanism the README names is binary space partitioning. In practice this means the visible area is repeatedly split, and each split produces two regions that can themselves be split again. A new window does not float on top of the arrangement; it becomes a leaf in the tree, and the tree is re-rendered. That is why the layout stays gapless without manual sizing, and why removing a window causes the remaining ones to expand into the freed space.

The architecture has two layers that matter for anyone evaluating the trade-offs. The first is the Accessibility API, which yabai must be granted permission to use and which it requests on launch. The second is a scripting addition injected into Dock.app, which the README says requires System Integrity Protection to be partially disabled. The scripting addition is what enables control of the window server, described in the README as the sole owner of all window connections. Some features live on the first layer and work with SIP intact. The elevated-privilege features do not.

That split is the single most important thing to understand before installing. It is not a configuration preference. It is an architectural boundary that decides which parts of the tool are available to you, and the README frames the SIP change as optional while also stating plainly that it enables additional features.

Installing yabai and Running a First Command

The README does not inline installation steps. It directs readers to the yabai wiki, which it says has both brief and detailed installation instructions for multiple installation methods, and also explains how to uninstall yabai completely. Sample configuration files live in the examples directory, and the repository ships examples/yabairc and examples/skhdrc. Because the README does not reproduce the install commands, the honest starting point is the wiki rather than a command copied from this page.

What the repository does give you is the shape of the configuration. The example files are the reference for what a working setup looks like, and the documentation under doc/ is where the command surface is described. A minimal path looks like this: install through the method the wiki documents, launch yabai, and grant the Accessibility permission when it asks. The README is explicit that the application must be restarted after access has been granted, so a first launch that appears to do nothing is expected behaviour rather than a failure.

If you build from source or install from HEAD, the README adds a step that release users do not face: the binary must be codesigned so it retains its accessibility and automation privileges when updated or rebuilt. Skipping that means re-granting permissions after every rebuild.

The example configuration is where you would set your own defaults, and the skhd example is where keyboard shortcuts are defined if you use skhd. Copying examples/yabairc into place is the conventional starting move, but the README does not state a required destination path, so treat the wiki as the authority on where the file belongs.

Where yabai Breaks or Becomes the Wrong Tool

The caveats table in the README is unusually candid, and several entries describe failures rather than preferences. Windows that use native macOS tabs, such as Terminal and Finder, do not behave correctly when creating tabs; the README links issue 68 and suggests avoiding tabs in those applications, choosing alternatives that do not use NSDocument's tab system, or making those windows float using rules. That is a genuine limitation with no configuration fix, only a workaround.

The Finder Desktop is another one. Some people disable the desktop window with an undocumented defaults write command, and the README states that doing so breaks focusing of empty spaces. The remedy it gives is to re-activate the Finder Desktop. If your existing setup depends on hiding that window, yabai and your setup are in conflict.

Space ordering is conditional on system settings that are easy to overlook. The README says "Automatically rearrange Spaces based on most recent use" should be disabled for commands that rely on the ordering of spaces to work reliably. On macOS 14.x and later it adds two more: "Show Items On Desktop" should be enabled and "Click wallpaper to reveal Desktop" should be set to "Only in Stage Manager" for display and space focus commands to work reliably in multi-display configurations. These are not optional tweaks. They are preconditions, and a multi-display user who ignores them will see commands misbehave.

The README also carries a disclaimer telling you to use the software at your own discretion and acknowledging the risk that comes from disabling System Integrity Protection. If you are not willing to accept that risk, the elevated-privilege feature set is simply off the table, and yabai becomes a smaller tool than the one described in its feature list.

How yabai Differs from Other macOS Window Managers

The comparison that matters on macOS is between yabai and the window managers that do not require disabling System Integrity Protection. Rectangle and similar tools move and resize windows through the Accessibility API and keyboard shortcuts, but they do not reflow a layout tree automatically. You press a shortcut, the window snaps to a region, and the remaining windows stay where they were. yabai's binary space partitioning means the arrangement is recomputed as windows appear and disappear, which is a different interaction model, not a faster version of the same one.

A more honest framing is that yabai trades setup cost and system risk for automation. The scripting addition injected into Dock.app is what buys control of the window server, and that is what makes features like disabling space-switching animations possible. A window manager that never touches SIP cannot offer those features, by construction. The choice is not which tool is better but whether the extra capability is worth the boundary you cross to get it.

The command line interface is the other differentiator. yabai is scriptable, and the README positions it as something you drive with an intuitive command line interface plus user-defined shortcuts. Tools built around a menu bar or a preferences pane are easier to start with and harder to automate. If your workflow involves scripts that react to window state, that distinction decides the choice.

Maintenance, Releases and the MIT Licence

The repository is not archived and the last push was on 2026-06-14, so the codebase is recent. The release cadence visible in the tags is frequent: v7.1.25 on 2026-05-08, v7.1.24 on 2026-04-24, and v7.1.23 on 2026-04-20. Three releases inside a month suggests active patching rather than a frozen project, though the version numbers also tell you these are point releases, not a new major line.

The upgrade cost is tied to how you installed it. If you build from source or install from HEAD, the README's codesigning caveat means every rebuild is followed by a codesign step, otherwise the binary loses its accessibility and automation privileges. Release installs do not carry that burden. That asymmetry is worth weighing before choosing the source route for a marginal version advantage.

The licence is MIT. The README describes it as a short and simple permissive license with conditions only requiring preservation of copyright and license notices, and notes that licensed works, modifications, and larger works may be distributed under different terms and without source code. Nothing in that restricts commercial use or redistribution. This is a description of the licence text, not legal advice; if you are redistributing yabai inside a product, read LICENSE.txt yourself.

Editorial conclusion

Adopt yabai if you live in a terminal, accept that macOS window control means granting Accessibility access, and want a scriptable layout engine rather than a mouse-driven one. Skip it if you are unwilling to touch System Integrity Protection or to maintain a configuration file, because a large part of what people expect from a tiling manager sits behind that boundary. Before committing, confirm your macOS version appears in the requirements table, check that "Displays have separate Spaces" is enabled, and decide whether you are installing a release build or compiling from source, since the latter requires codesigning the binary.

Frequently asked questions

Official sources

1. asmvik/yabai on GitHub
2. Issues
3. License: MIT
4. README
5. Releases