Configuration

The file

oxwm reads ~/.config/oxwm/config.lua at startup. To use a different file, pass it on the command line:

oxwm --config ~/dotfiles/oxwm.lua

The file is plain Lua 5.4. oxwm puts one global table in scope, oxwm, and everything you configure goes through functions on it.

Two kinds of functions

Most functions are settings. They take effect when the config runs:

oxwm.set_terminal("st")
oxwm.border.set_width(2)
oxwm.gaps.set_inner(5, 5)

The rest are actions. An action does nothing when you call it. It returns a value that you hand to a keybinding, and it runs when the key is pressed:

oxwm.key.bind({ "Mod4" }, "Q", oxwm.client.kill())
oxwm.key.bind({ "Mod4" }, "Return", oxwm.spawn_terminal())

Note the parentheses. You pass the result of oxwm.client.kill(), not the function itself.

A small config

This is enough to get a usable session:

local modkey = "Mod4"

oxwm.set_terminal("st")
oxwm.set_modkey(modkey)
oxwm.set_tags({ "1", "2", "3", "4", "5", "6", "7", "8", "9" })

oxwm.border.set_width(2)
oxwm.border.set_focused_color("#6dade3")
oxwm.border.set_unfocused_color("#444444")

oxwm.key.bind({ modkey }, "Return", oxwm.spawn_terminal())
oxwm.key.bind({ modkey }, "D", oxwm.spawn("dmenu_run"))
oxwm.key.bind({ modkey }, "Q", oxwm.client.kill())
oxwm.key.bind({ modkey }, "J", oxwm.client.focus_stack(1))
oxwm.key.bind({ modkey }, "K", oxwm.client.focus_stack(-1))
oxwm.key.bind({ modkey, "Shift" }, "R", oxwm.restart())
oxwm.key.bind({ modkey, "Shift" }, "Q", oxwm.quit())

for i = 1, 9 do
    oxwm.key.bind({ modkey }, tostring(i), oxwm.tag.view(i - 1))
    oxwm.key.bind({ modkey, "Shift" }, tostring(i), oxwm.tag.move_to(i - 1))
end

oxwm.autostart("picom")

Because it is Lua, you can use variables, loops and functions wherever they save typing.

Basic settings

Terminal

oxwm.set_terminal("alacritty")

This is the command oxwm.spawn_terminal() runs.

Modkey

oxwm.set_modkey("Mod4")

This sets the modifier for the mouse bindings. It does not change your keybindings. Those name their modifiers one by one, which is why most configs keep a modkey variable and use it in both places.

Valid names are Mod4 (Super), Mod1 (Alt), Shift and Control.

Autostart

oxwm.autostart("picom")
oxwm.autostart("feh --bg-scale ~/wallpaper.jpg")
oxwm.autostart("dunst")

Each command runs once when oxwm starts.

Reloading

Bind oxwm.restart() to a key. The default is Mod+Shift+R. It reads the config again and applies it without restarting X, and your windows stay on their tags.

If the new config has a Lua error, check it with:

oxwm --validate

Editor support

oxwm ships type definitions for the Lua language server, so your editor can complete function names and check arguments. They are installed at /usr/share/oxwm/oxwm.lua, and the source is templates/oxwm.lua.

Tell the language server where they are with ~/.config/oxwm/.luarc.json:

{
  "workspace.library": ["/usr/share/oxwm"]
}

Then add this line to the top of config.lua:

---@module 'oxwm'