Where Is the AeroSpace Config File?
AeroSpace reads aerospace.toml from your home folder or the XDG aerospace dir, and errors if both exist.
Last updated
AeroSpace looks in exactly two places: ~/.aerospace.toml and ${XDG_CONFIG_HOME}/aerospace/aerospace.toml (which is ~/.config/aerospace/aerospace.toml unless you set XDG_CONFIG_HOME). No config in either place means the built-in defaults load. Config in both places means an ambiguity error, not a merge.
That strictness is the whole story. Pick one home for the file and keep the other absent. Most people use ~/.aerospace.toml since every guide references it, while XDG purists take the namespaced path. Either works identically.
Where AeroSpace stores this, by platform
~/.aerospace.toml
TOML config. Exactly one of the two documented locations may exist. Bootstrap from the default-config.toml inside the app bundle.
Frequently asked questions
AeroSpace complains my config is ambiguous. Why?
Delete or merge one copy. AeroSpace reports ambiguity instead of guessing, so a config that previously worked can start failing after you copy it to the second location for safekeeping.
How do I create my first AeroSpace config?
Copy /Applications/AeroSpace.app/Contents/Resources/default-config.toml to ~/.aerospace.toml and edit from there. The default file documents every key, so starting from it beats writing blind.
Notice an outdated path? Let us know.