Where Is the awesome WM Config File?
Where the awesome window manager looks for rc.lua on Linux, and how to start customizing it safely.
Last updated
awesome reads a Lua script called rc.lua at startup. It checks the user path first (~/.config/awesome/rc.lua), then system fallbacks under /etc/xdg. The first file found wins.
The package ships a working default. Copy it down before changing anything. Editing the system file directly works until the next package update replaces it, so the user copy is the durable home for your setup.
Where awesome stores this, by platform
~/.config/awesome/rc.lua
Main user config in Lua. Copy from /etc/xdg/awesome/rc.lua. Validate with awesome -k. Custom modules usually live beside it in the same folder.
Frequently asked questions
How do I create my own awesome config?
Create ~/.config/awesome/ and copy /etc/xdg/awesome/rc.lua into it, then edit the copy. awesome reads the user file first and falls back to the system one. Check edits with awesome -k and reload with Mod+Control+r.
Can I test a config without breaking my session?
Pass -c with a path, e.g. awesome -c ~/.config/awesome/rc.lua.test. Pair it with a test tool like awmtt running under Xephyr so a broken config cannot lock your live session.
Notice an outdated path? Let us know.