Where Does yabai Look for Its Config?
Where yabai looks for its yabairc shell config, the lookup order it follows, and the flag for custom paths..
Last updated
yabai reads a single shell script as its configuration, executed before the window manager launches. The lookup tries XDG config home first, then the plain config path, then the legacy home dotfile. A command line flag overrides everything with an explicit path.
Because the config is executable shell, mistakes fail loudly at launch rather than silently. Keep it under version control like any dotfile you depend on daily. The scripting addition handshake with macOS stays separate from config location concerns.
Where yabai stores this, by platform
~/.config/yabai/yabairc
Preferred modern location for the executable yabairc script. Falls back to ~/.yabairc legacy path when absent. The --config flag bypasses lookup with an explicit file. Keep it valid shell; breakage blocks launch.
Frequently asked questions
where do I put my yabai config
Create ~/.config/yabai/yabairc or ~/.yabairc as an executable shell script with your rules. The wiki lists the lookup order with XDG first. Old guides insisting on home directory only predate XDG support.
how do I use a custom config path
Launch with --config pointing at the file to override all defaults. The path then skips the standard lookup entirely. Scripting service setups use this to test configs safely.
yabai ignores my config, why
Make it executable so yabai runs it as a script, and keep it valid shell. A broken rc fails the whole launch with little explanation. Validate by running the file directly in a terminal first.
Notice an outdated path? Let us know.