Configuration Reference

Overview

This document provides a complete reference for SamWM configuration options.

Configuration File Location

Default location: ~/.config/samwm/config.lua

Override with command line flag:

samwm -config /path/to/config.lua

Configuration API

samwm.general(options)

General compositor settings.

samwm.general({
    border_size = 2,           -- Window border width (pixels)
    gaps_inner = 5,            -- Gap between windows (pixels)
    gaps_outer = 10,           -- Gap to screen edges (pixels)
    resize_corner = 10,        -- Resize corner size (pixels)
    focus_follows_mouse = true, -- Focus follows mouse cursor
    mouse_mod_move = "SUPER",  -- Modifier for mouse move
    mouse_mod_resize = "SUPER" -- Modifier for mouse resize
})

Options

Option	Type	Default	Range	Description
`border_size`	integer	2	0-20	Window border width in pixels
`gaps_inner`	integer	5	0-100	Gap between windows in pixels
`gaps_outer`	integer	10	0-100	Gap between windows and screen edges
`resize_corner`	integer	10	5-50	Size of resize corner area
`focus_follows_mouse`	boolean	true	-	Whether focus follows mouse cursor
`mouse_mod_move`	string	“SUPER”	-	Modifier key for moving windows
`mouse_mod_resize`	string	“SUPER”	-	Modifier key for resizing windows

samwm.layout(options)

Layout algorithm settings.

samwm.layout({
    master_factor = 0.55,      -- Master area ratio (0.0-1.0)
    master_count = 1,          -- Number of master windows
    smart_gaps = true,         -- Disable gaps with single window
    default = "master-stack"   -- Default layout algorithm
})

Options

Option	Type	Default	Range	Description
`master_factor`	float	0.55	0.1-0.9	Ratio of screen width for master area
`master_count`	integer	1	1-10	Number of windows in master area
`smart_gaps`	boolean	true	-	Disable gaps when only one window
`default`	string	“master-stack”	-	Default layout algorithm

Available Layouts

master-stack - Master area with stack (default)
fullscreen - All windows fullscreen
floating - Manual floating layout

samwm.input(options)

Input device settings.

samwm.input({
    keyboard = {
        repeat_rate = 25,      -- Key repeat rate (chars/sec)
        repeat_delay = 600,    -- Repeat delay (ms)
        numlock = true,        -- Enable numlock by default
        capslock = false       -- Enable capslock by default
    },
    mouse = {
        sensitivity = 0.0,     -- Mouse sensitivity (-1.0 to 1.0)
        natural_scroll = false, -- Natural scrolling
        acceleration = "flat"  -- Acceleration profile
    },
    touchpad = {
        disable_while_typing = true,  -- Disable while typing
        natural_scroll = true,        -- Natural scrolling
        tap_to_click = true,          -- Tap to click
        scroll_factor = 1.0           -- Scroll speed multiplier
    }
})

Keyboard Options

Option	Type	Default	Range	Description
`repeat_rate`	integer	25	1-100	Key repeat rate in characters per second
`repeat_delay`	integer	600	100-5000	Delay before repeat starts (ms)
`numlock`	boolean	true	-	Enable numlock by default
`capslock`	boolean	false	-	Enable capslock by default

Mouse Options

Option	Type	Default	Range	Description
`sensitivity`	float	0.0	-1.0 to 1.0	Mouse sensitivity
`natural_scroll`	boolean	false	-	Reverse scroll direction
`acceleration`	string	“flat”	flat, adaptive	Acceleration profile

Touchpad Options

Option	Type	Default	Range	Description
`disable_while_typing`	boolean	true	-	Disable touchpad while typing
`natural_scroll`	boolean	true	-	Reverse scroll direction
`tap_to_click`	boolean	true	-	Enable tap to click
`scroll_factor`	float	1.0	0.1-10.0	Scroll speed multiplier

samwm.appearance(options)

Visual appearance settings.

samwm.appearance({
    active_border = "#89b4fa",    -- Active window border color
    inactive_border = "#585b70",  -- Inactive window border color
    urgent_border = "#f38ba8",    -- Urgent window border color
    background = "#1e1e2e",       -- Background color
    font = "monospace",           -- Font family
    font_size = 12                -- Font size (points)
})

Options

Option	Type	Default	Description
`active_border`	string	“#89b4fa”	Active window border color (hex)
`inactive_border`	string	“#585b70”	Inactive window border color (hex)
`urgent_border`	string	“#f38ba8”	Urgent window border color (hex)
`background`	string	“#1e1e2e”	Root window background color (hex)
`font`	string	“monospace”	Font family name
`font_size`	integer	12	Font size in points

samwm.bind(modifier, key, action, description)

samwm.bind("SUPER", "Return", "exec terminal", "Open terminal")

Parameters

Parameter	Type	Required	Description
`modifier`	string	Yes	Modifier key(s)
`key`	string	Yes	Key to press
`action`	string	Yes	Action to execute
`description`	string	No	Human-readable description

Modifiers

SUPER - Windows/Meta key
ALT - Alt key
CTRL - Control key
SHIFT - Shift key

Combine with space: "SUPER SHIFT" for multiple modifiers.

Actions

Action	Description	Example
`exec <cmd>`	Execute command	`"exec firefox"`
`close`	Close active window	`"close"`
`exit`	Exit SamWM	`"exit"`
`focus next`	Focus next window	`"focus next"`
`focus prev`	Focus previous window	`"focus prev"`
`fullscreen`	Toggle fullscreen	`"fullscreen"`
`togglefloating`	Toggle floating	`"togglefloating"`
`workspace <n>`	Switch workspace	`"workspace 1"`
`movetoworkspace <n>`	Move to workspace	`"movetoworkspace 2"`
`scratchpad`	Toggle scratchpad	`"scratchpad"`
`resize`	Resize master factor	`"resize grow_width"`
`swap`	Swap with neighbor	`"swap left"`
`layout <name>`	Set layout	`"layout dwindle"`

samwm.windowrule(match, actions)

Define rules for specific windows.

samwm.windowrule(
    { class = "Firefox", title = "Picture-in-Picture" },
    { float = "true", size = "800 600" }
)

Match Criteria

Criterion	Type	Description
`class`	string	Window class name
`title`	string	Window title
`instance`	string	Window instance name

Actions

Action	Value	Description
`float`	“true”/“false”	Force floating
`tile`	“true”/“false”	Force tiling
`size`	“W H”	Set window size
`position`	“X Y”	Set window position
`workspace`	“n”	Move to workspace

samwm.exec(command)

Execute a command on startup.

samwm.exec("waybar")
samwm.exec("nm-applet")

Complete Example

-- General settings
samwm.general({
    border_size = 2,
    gaps_inner = 5,
    gaps_outer = 10,
    focus_follows_mouse = true
})

-- Layout
samwm.layout({
    master_factor = 0.55,
    master_count = 1,
    smart_gaps = true
})

-- Input
samwm.input({
    keyboard = { repeat_rate = 25, repeat_delay = 600 },
    mouse = { sensitivity = 0.0 },
    touchpad = { natural_scroll = true }
})

-- Appearance
samwm.appearance({
    active_border = "#89b4fa",
    inactive_border = "#585b70",
    background = "#1e1e2e"
})

-- Keybindings
samwm.bind("SUPER", "Return", "exec terminal")
samwm.bind("SUPER", "Q", "close")
samwm.bind("SUPER", "1", "workspace 1")

-- Window rules
samwm.windowrule({ class = "Firefox" }, { float = "true" })

-- Startup
samwm.exec("waybar")

Validation

Configuration values are validated on load:

Numeric values are clamped to valid ranges
Invalid layout names fall back to “master-stack”
Unknown keybinding actions are logged as warnings
Invalid colors are ignored

Reloading

SamWM supports hot-reloading configuration without restarting:

kill -HUP $(pidof samwm)

Or via IPC:

samwm-msg reload

Keybindings and window rules update immediately. See Hot Reload for full details.

Debugging

Run with verbose logging to see configuration parsing:

samwm -v -config ./config.lua