DOCSEARCHbyAlgolia
Submit Docs

yabai

repository·master·Indexed 12 days ago

https://github.com/asmvik/yabai

A tiling window management utility for macOS that extends the native window manager using a binary space partitioning (BSP) algorithm. It provides a command-line interface to control windows, spaces, and displays, and supports advanced features like window shadows and opacity via an optional scripting-addition.

Tokens
4K
Snippets
12
Records
17
Agent score
79%

What's inside yabai

  1. Load or uninstall the Scripting Addition

    master

    The Scripting Addition (yabai.osax) provides advanced features like window shadows, opacity, and space manipulation.

    Requirements:

    • System Integrity Protection (SIP) must be partially disabled.

    Commands:

    • --load-sa: Installs and updates the scripting addition into Dock.app at /Library/ScriptingAdditions/yabai.osax.
    • --uninstall-sa: Uninstalls the scripting addition. Must be run as root.
    sudo yabai --uninstall-sa

  2. Install and configure yabai

    master

    yabai is a tiling window management utility for macOS that extends the built-in window manager. It uses a binary space partitioning algorithm to automatically manage window layouts.

    Installation

    Detailed installation instructions for various methods and uninstallation procedures are available in the yabai wiki.

    Configuration

    • Configuration Files: Sample configuration files are located in the examples directory of the repository. For full details on configuration keys, refer to the official documentation.
    • Keyboard Shortcuts: yabai does not manage keyboard shortcuts itself. You should use skhd or other third-party software to define user-defined shortcuts to call the yabai CLI.

  3. System requirements and permissions for yabai

    master

    Before using yabai, ensure your macOS environment meets the following requirements:

    Supported Operating Systems

    • Intel x86-64: Big Sur 11.0.0+, Monterey 12.0.0+, Ventura 13.0.0+, Sonoma 14.0.0+, Sequoia 15.0+, and Tahoe 26.0+.
    • Apple Silicon: Monterey 12.0.0+, Ventura 13.0.0+, Sonoma 14.0.0+, Sequoia 15.0+, and Tahoe 26.0+.

    Required Permissions

    • Accessibility API: Required for window management. You must grant permission via macOS settings and restart yabai after granting access.
    • Screen Recording: Required only if you want to enable window animations. You must grant permission and restart yabai after access is granted.

    Required macOS Settings

    To ensure proper functionality, the following settings must be configured:

    • Displays have separate Spaces:
      • macOS 11.x, 12.x: Enabled in the Mission Control pane.
      • macOS 13.x, 14.x, 15.x, 26.x: Enabled in the Desktop & Dock tab, inside the Mission Control pane.
    • Automatically rearrange Spaces based on most recent use:
      • Should be disabled for commands relying on space ordering to work reliably (Settings location depends on macOS version, typically under Mission Control or Desktop & Dock).

  4. Configure global and space settings

    master

    Settings can be managed using the yabai -m config command.

    Global Settings Syntax: yabai -m config <global setting>

    Space Settings Syntax: yabai -m config [--space '<SPACE_SEL>'] <space setting>

    Common Global Settings:

    • debug_output: <on|off>
    • mouse_follows_focus: <on|off>
    • focus_follows_mouse: autofocus|autoraise|off
    • window_opacity: <0.0 to 1.0> (Requires SIP disabled)
    • window_shadow: <on|off> (Requires SIP disabled)
    • window_animation_duration: <0.0 to 1.0> (Requires Screen Recording permissions and SIP disabled)

    Common Space Settings:

    • layout: bsp|stack|float
    • split_type: vertical|horizontal|auto
    • window_gap: <integer>
    • top_padding, bottom_padding, left_padding, right_padding: <integer>
    yabai -m config mouse_follows_focus on
yabai -m config --space 1 layout bsp

  5. Configure macOS settings for multi-display and stage manager

    master

    For reliable display and space focus commands in multi-display configurations (specifically on macOS 14.x, 15.x, and 26.x), configure the following in the Desktop & Dock tab:

    1. Show Items On Desktop: Must be enabled (inside the Desktop & Stage Manager pane).
    2. Click wallpaper to reveal Desktop: Must be set to "Only in Stage Manager" (inside the Desktop & Stage Manager pane).

  6. Install the scripting-addition for advanced features

    master

    To enable advanced features like window shadows, opacity, and certain space manipulations, you must load the scripting-addition into Dock.app.

    Note: This requires System Integrity Protection (SIP) to be partially disabled.

    • Load/Install: yabai --load-sa (installs/updates the .osax file at /Library/ScriptingAdditions/yabai.osax).
    • Uninstall: yabai --uninstall-sa (must be run as root).
    yabai --load-sa

  7. Install and manage the yabai service

    master

    Use the following commands to manage the yabai background service via launchd:

    • Install service file: yabai --install-service (writes the plist to ~/Library/LaunchAgents/com.asmvik.yabai.plist).
    • Start service: yabai --start-service (enables, loads, and starts the service; installs the file if missing).
    • Stop service: yabai --stop-service (stops and unloads the running instance).
    • Restart service: yabai --restart-service (attempts to restart the instance).
    • Uninstall service: yabai --uninstall-service (removes the plist from disk).
    yabai --install-service
yabai --start-service

  8. Troubleshoot yabai window management issues

    master

    If yabai is not behaving as expected, check the following common causes:

    Finder Desktop Issues

    If you have disabled the Finder Desktop using defaults write com.apple.finder CreateDesktop -bool false, yabai may fail to focus empty spaces. To fix this, re-activate the Finder Desktop with:

    defaults write com.apple.finder CreateDesktop -bool true

    NSDocument-based Applications

    Applications that use native macOS tabs (like Terminal or Finder) may not behave correctly when creating tabs. To resolve this, avoid creating tabs in these apps, use alternative applications, or define floating rules in your yabai configuration to make these windows float.

    Code Signing

    If you are building from source or installing from HEAD, you must codesign the binary to ensure it retains its Accessibility and Automation privileges after updates or rebuilds.

  9. React to events using Signals

    master

    Signals allow you to execute arbitrary shell commands in response to specific window manager events.

    Syntax: yabai -m signal '<COMMAND>'

    Command:

    • --add event='<EVENT>' action='<ACTION>' [label='<LABEL>'] [app[!]='<REGEX>'] [title[!]='<REGEX>'] [active='yes|no']

    Common Events and Arguments:

    • window_created: Passes $YABAI_WINDOW_ID.
    • window_focused: Passes $YABAI_WINDOW_ID.
    • space_changed: Passes $YABAI_SPACE_ID, $YABAI_SPACE_INDEX, $YABAI_RECENT_SPACE_ID, $YABAI_RECENT_SPACE_INDEX.
    • application_launched: Passes $YABAI_PROCESS_ID.
    • display_added: Passes $YABAI_DISPLAY_ID, $YABAI_DISPLAY_INDEX.

    Action: An arbitrary command executed via /usr/bin/env sh -c. Arguments are passed through environment variables (e.g., $YABAI_WINDOW_ID).

    yabai -m signal --add event='window_focused' action='osascript -e "display notification \"Focused!\""'

  10. Define window rules

    master

    Rules allow you to automatically apply settings to windows based on filters like application name, title, or role.

    Syntax: yabai -m rule '<COMMAND>'

    Commands:

    • --add [--one-shot] '<ARGUMENTS>': Add a new rule. --one-shot rules are removed after applying once.
    • --apply ['<RULE_SEL>' | '<ARGUMENT>']: Apply rules to existing windows.
    • --remove '<RULE_SEL>': Remove a rule by index or label.
    • --list: List all registered rules.

    Arguments:

    • app[!]='<REGEX>': Match application name (use ! to invert).
    • title[!]='<REGEX>': Match window title.
    • manage='<on|off>': Force window to be tiled or floating.
    • sticky='<on|off>': Window appears on all spaces (requires SIP disabled).
    • space='<SPACE_SEL>': Send window to specific space.
    • label='<LABEL>': Assign a unique name to the rule.
    yabai -m rule --add app='^Terminal$' manage=off

  11. Query window, space, and display information

    master

    Retrieve JSON data about the current state of the window manager using yabai -m query '<COMMAND>'.

    Commands:

    • --displays: Information about all displays.
    • --spaces: Information about all spaces.
    • --windows: Information about all windows.

    Filtering: Use --display <DISPLAY_SEL>, --space <SPACE_SEL>, or --window <WINDOW_SEL> to constrain results.

    Properties: You can request specific fields by providing a comma-separated string of property names.

    Example Window Properties: id, pid, app, title, frame (x, y, w, h), display, space, is-floating, is-visible, has-focus.

    yabai -m query --windows --window recent --properties app,title,frame

  12. Control displays, spaces, and windows

    master

    Yabai provides direct commands to manipulate the window management environment.

    Display Commands: yabai -m display ['<DISPLAY_SEL>'] '<COMMAND>'

    • --focus <DISPLAY_SEL>: Focus a display.
    • --label <LABEL>: Assign an alias to a display.

    Space Commands: yabai -m space ['<SPACE_SEL>'] '<COMMAND>'

    • --focus <SPACE_SEL>: Focus a space.
    • --switch <SPACE_SEL>: Swaps the selected space with the target space (requires SIP disabled).
    • --create ['<DISPLAY_SEL>']: Create a new space.
    • --destroy ['<SPACE_SEL>']: Remove a space.
    • --layout <layout>: Set layout (bsp|stack|float).

    Window Commands: yabai -m window ['<WINDOW_SEL>'] '<COMMAND>'

    • --focus ['<WINDOW_SEL>']: Focus a window.
    • --display <DISPLAY_SEL>: Send window to a display.
    • --space <SPACE_SEL>: Send window to a space.
    • --swap <WINDOW_SEL>: Swap window positions.
    • --toggle <property>: Toggle properties like float, sticky, shadow, or zoom-fullscreen (some require SIP disabled).
    yabai -m window --focus next
yabai -m window --space 2