FAQ

General

How do I start SamWM?

From a TTY:

make setup-config  # First time only
WAYLAND_DISPLAY=wayland-0 samwm

How do I reload config without restarting?

Press SUPER+SHIFT+C or run:

samwm-msg reload

How do I exit SamWM?

Press SUPER+M or run:

samwm-msg exit

Keybindings

My keybinding doesn’t work

• Check for typos in the key name (case-sensitive)
• Make sure the modifier is correct (SUPER, not SUPER+CTRL for example)
• Verify the action exists (check [[Keybindings]] page)
• Check config file for syntax errors: lua -e 'dofile("~/.config/samwm/config.lua")'

How do I open a terminal?

Add this to your config:

samwm.bind("SUPER", "Return", "exec alacritty", "Terminal")

Change alacritty to your terminal emulator.

Windows

A window won’t tile, it’s floating

Apply a window rule:

samwm.windowrule(
    { class = "the-app-class" },
    { float = "false" }
)

Find the app class with samwm-msg windows or xprop | grep CLASS.

Windows open on wrong workspace

Use window rules:

samwm.windowrule(
    { class = "Firefox" },
    { workspace = "2" }
)

Layouts

How do I change the default layout?

samwm.layout({
    default = "dwindle"
})

Available layouts: master-stack, dwindle, bsp, columns, floating, fullscreen.

Smart gaps still showing with one window

Smart gaps disable when only one tiled window is visible. Floating windows don’t count. Close or move the extra windows.

Multi-Monitor

Windows moved to disconnected monitor

When a monitor disconnects, SamWM moves windows to the next available output. Use samwm-msg windows to find them.

Second monitor shows black screen

1. Check the output is detected: samwm-msg outputs
2. Verify cable connection
3. Try: wlr-randr to see available outputs

Performance

High CPU usage

• Check for animations: disable in config
• Avoid transparency effects
• Reduce gaps_inner and gaps_outer if very high

Slow window operations

Make sure you have the latest version. Performance fixes are added regularly.

Debugging

View SamWM logs

Logs go to standard error. Run SamWM from a terminal to see them:

WAYLAND_DISPLAY=wayland-0 samwm 2>&1 | tee samwm.log

Check config for errors

lua ~/.config/samwm/config.lua