Skip to main content

Migrating from AwesomeWM

Quick Compatibility Check​

Before migrating, scan your config for potential issues:

somewm --check ~/.config/awesome/rc.lua

To only fail on issues that would actually hang the compositor (ignoring warnings):

somewm --check ~/.config/awesome/rc.lua --check-level=critical

This checks for:

  • Lua syntax errors - Caught before execution
  • X11-specific APIs - Functions like awesome.get_xproperty() that don't exist on Wayland
  • Blocking X11 tools - Calls to xrandr, xdotool, xprop via io.popen() that would hang
  • Missing local modules - require() statements for files that can't be found
  • Luacheck issues - Code quality warnings (if luacheck is installed)

Severity Levels​

Issues are categorized by severity:

  • CRITICAL - Will fail or hang on Wayland (must fix)
  • WARNING - Needs a Wayland alternative
  • INFO - May not work but won't break config

Example output:

somewm config compatibility report
====================================
Config: /home/user/.config/awesome/rc.lua

X CRITICAL:
  rc.lua:45 - io.popen with xrandr (blocks)
    → Use screen:geometry() or screen.outputs instead

! WARNING:
  rc.lua:112 - maim screenshot tool
    → Use awful.screenshot or grim instead

Summary: 1 critical, 1 warning

Suppressing False Positives​

If --check flags a pattern you've already handled (e.g. behind a runtime guard), add -- somewm:ignore to that line:

awful.spawn("flameshot gui") -- somewm:ignore using XDG portal on Wayland

The suppression also works at runtime, not just in --check mode. SomeWM's startup prescan will skip suppressed lines too.

X11 Pattern Replacements​

Screen/Display Information​

X11 PatternWayland Alternative
io.popen("xrandr")screen:geometry() or screen.outputs
xdpyinfoscreen.geometry properties
-- X11 (don't do this)
local handle = io.popen("xrandr | grep ' connected'")

-- Wayland
for s in screen do
    print(s.geometry.width .. "x" .. s.geometry.height)
    for name, output in pairs(s.outputs) do
        print("  Output: " .. name)
    end
end

Window/Client Information​

X11 PatternWayland Alternative
io.popen("xdotool")awful.spawn() or client:send_key()
io.popen("xprop")client.class, client.instance
awesome.register_xproperty()Not needed on Wayland
-- X11 (don't do this)
local handle = io.popen("xprop -id " .. c.window)

-- Wayland
local class = c.class      -- e.g., "firefox"
local instance = c.instance  -- e.g., "Navigator"

Screenshots​

X11 PatternWayland Alternative
scrotawful.screenshot or grim
maimawful.screenshot or grim
import (ImageMagick)grim
-- X11 (don't do this)
awful.spawn("scrot ~/screenshot.png")

-- Wayland
awful.screenshot({ directory = "~" })
-- or
awful.spawn("grim ~/screenshot.png")

Input Simulation​

X11 PatternWayland Alternative
xdotool keyKeybindings, or wait for root.fake_input()
xdotool mousemoveNot yet implemented
note

root.fake_input() is currently a stub in SomeWM. Virtual input requires wlroots virtual pointer/keyboard protocols which are planned for a future release.

GTK/GDK via LGI​

PatternSeverityNotes
lgi.require("Gtk")WARNINGSomeWM preloads an empty override to prevent deadlock, but display-dependent GTK features won't work
lgi.require("Gdk")CRITICALNo mitigation. GDK init connects to the display server and will deadlock during config load

If you need GTK for icon lookup or similar, load it lazily after startup:

-- Don't load at the top level
-- local Gtk = lgi.require("Gtk")

-- Load lazily inside a callback instead
awful.spawn.easy_async("true", function()
    local Gtk = lgi.require("Gtk")
    -- safe to use here, event loop is running
end)

What Works Unchanged​

Most of your config will work without changes:

  • All awful. modules* - layouts, keybindings, rules, spawn, etc.
  • All gears. modules* - timers, shapes, filesystem, etc.
  • All wibox. widgets* - text, image, progressbar, etc.
  • Naughty notifications
  • Theming - beautiful.* properties
  • Client rules - awful.rules.rules
  • Signals - client.connect_signal(), screen.connect_signal(), etc.

Automatic Detection​

SomeWM will automatically detect and skip configs that contain X11-specific code. If your config is skipped, SomeWM will show a notification explaining which X11 pattern was detected and suggest alternatives.

If you share a config between AwesomeWM and SomeWM, you can detect which compositor is running:

local is_somewm = awesome.release == "somewm"

if is_somewm then
    awful.spawn("grim ~/screenshot.png")
else
    awful.spawn("scrot ~/screenshot.png")
end

Testing Your Config​

  1. Run the compatibility check first:

    somewm --check ~/.config/awesome/rc.lua

  2. Fix any CRITICAL issues

  3. Try loading the config:

    somewm -c ~/.config/awesome/rc.lua

  4. Check debug output if needed:

    somewm -d -c ~/.config/awesome/rc.lua 2>&1 | tee migration.log

Common Migration Scenarios​

Autostart Scripts​

If you're spawning X11 tools on startup:

-- X11 (problematic)
awful.spawn.once("xset r rate 200 30")  -- Keyboard repeat

-- Wayland (use awful.input)
awful.input.keyboard_repeat_delay = 200
awful.input.keyboard_repeat_rate = 30

Status Bar with X11 Tools​

-- X11 (won't work)
awful.widget.watch("xbacklight -get", 5, function(widget, stdout)
    widget:set_text(stdout)
end)

-- Wayland (use brightnessctl or similar)
awful.widget.watch("brightnessctl -m | cut -d',' -f4", 5, function(widget, stdout)
    widget:set_text(stdout)
end)

Next Steps​