Skip to main content
Version: 2.0 (dev)

Wayland vs X11

This page explains why some AwesomeWM features work differently (or don't work) on Wayland.

Fundamental Differences​

AspectX11Wayland
Window managementClient-side hints, WM interpretsCompositor controls everything
DrawingServer-side or client-sideClient-side only (EGL/Vulkan)
InputGlobal accessPer-surface, security-focused
ScreenshotsAny app can captureRequires compositor support
Tray iconsX11 embed (_NET_SYSTEMTRAY)D-Bus (StatusNotifierItem)

What This Means for SomeWM​

No WM Restart​

X11: AwesomeWM can restart itself, re-reading config and reconnecting to windows.

Wayland: The compositor is the display server. Restarting it would disconnect all clients.

Workaround: Use Mod4 + Ctrl + r to reload your Lua configuration without restarting.

Different Systray​

X11: Tray icons are embedded X11 windows inside the wibox.

Wayland: Tray icons use the StatusNotifierItem (SNI) D-Bus protocol.

Impact: Most modern apps (NetworkManager, Discord, Bluetooth) support SNI. Legacy XEmbed-only apps won't show tray icons.

No Global Input Injection​

X11: xdotool and similar tools can inject input anywhere.

Wayland: Security model prevents apps from injecting input into other apps.

Impact: External tools like xdotool cannot inject input. root.fake_input() works, because it is the compositor doing the injecting (via wlr_seat), so automation goes through SomeWM itself. See Deviations for status.

Key Repeat Is Client-Side​

X11: The X server generates repeat events while a key is held, from its own per-key repeat table, which is on by default for ordinary keys.

Wayland: The compositor sends the repeat rate and delay once, along with the keymap. Each application does its own repeating, and asks the keymap whether the held key is allowed to repeat.

Impact: keyboard_repeat_rate and keyboard_repeat_delay set the timing, not which keys are eligible. Eligibility is a per-key flag in the keymap, so a layout can leave a key not repeating no matter what those properties say. This is not specific to SomeWM. The flag lives in the keymap and the application reads it, so the same layout behaves the same way under any Wayland compositor. See A key doesn't repeat when held if you hit this.

No X Properties​

X11: Windows can store arbitrary properties that persist across sessions.

Wayland: No equivalent mechanism exists.

Impact: awesome.register_xproperty() and related APIs are stubs.

Titlebar Border Positioning​

X11: Borders drawn OUTSIDE the window frame by X server.

Wayland: Borders are scene graph rectangles drawn around the client geometry. c:geometry() excludes the border, matching AwesomeWM; the window's on-screen footprint is the geometry plus border_width on each side.

Impact: Titlebars are inside the geometry and start INSIDE the border area (inset by border_width).

Partially Working Features​

XKB Layout Toggle​

X11: Toggle options like grp:alt_shift_toggle work because the X server intercepts the key combination and executes the layout switch.

Wayland: No X server exists to execute toggle logic. The key combination is just a regular key press that does nothing.

Impact: Sway, Hyprland, and other Wayland compositors have the same limitation.

Workaround: Use explicit keybindings to switch layouts programmatically. See Keyboard Layout Switching for complete examples.

awful.key({ "Mod1", "Shift" }, "space", function()
    local current = awesome.xkb_get_layout_group()
    awesome.xkb_set_layout_group((current + 1) % 2)
end)

Note: Static XKB options like ctrl:nocaps and compose:ralt work normally - only grp:* toggle options are affected.

See Also​