Skip to main content
Version: 2.0 (dev)

Launch

Starting SomeWM​

From a Display Manager​

sudo make install installs a Wayland session file, so you can select "SomeWM" from your display manager's session list (GDM, SDDM, etc.).

From a TTY​

dbus-run-session somewm

With a startup command (e.g., to launch a terminal):

dbus-run-session somewm -s 'alacritty'
D-Bus Session

dbus-run-session ensures D-Bus services (notifications, media keys, etc.) work correctly. If you're already in a D-Bus session (e.g., from a display manager), you can run somewm directly.

Configuration Locations​

SomeWM searches for configuration files in this order:

  1. ~/.config/somewm/rc.lua - Your personal config
  2. ~/.config/awesome/rc.lua - AwesomeWM compatibility (use your existing config!)
  3. System fallback - Default config installed with SomeWM

First Time Setup​

If you don't have a config yet, SomeWM will use the default configuration. To customize:

# Create config directory
mkdir -p ~/.config/somewm

# Copy default config to customize
cp /etc/xdg/somewm/rc.lua ~/.config/somewm/rc.lua
# Or for local install:
# cp ~/.local/etc/xdg/somewm/rc.lua ~/.config/somewm/rc.lua
NixOS

The nix-build approach installs only binaries. Get the default config from the source repository.

Essential Keybindings​

Enough to survive your first session (Mod4 is usually the Super/Windows key):

KeybindingAction
Mod4 + ReturnOpen terminal
Mod4 + Shift + cClose focused client
Mod4 + 1-9View tag 1-9
Mod4 + Ctrl + rReload configuration
Mod4 + Shift + qQuit SomeWM

Press Mod4 + s for the built-in cheat sheet with every binding, or see the Default Keybindings reference.

Troubleshooting​

"No config found" error​

Make sure you ran sudo make install. Running SomeWM directly from the build directory won't work because Lua libraries aren't in the expected paths.

Config loads but crashes immediately​

Enable debug logging to see what's happening:

somewm -d 2>&1 | tee somewm.log

Or with full wlroots debug output:

WLR_DEBUG=1 somewm 2>&1 | tee somewm.log

Look for lines containing error loading or error executing in the log.

Widgets not rendering​

This usually means LGI isn't found or is the wrong version. See Installation - LGI Troubleshooting.

Next Steps​