guides

Text Expansion on Wayland: Why It Breaks and What Actually Works

Trofin Sorin-IoanTrofin Sorin-IoanCTO, Lightning AssistJuly 26, 20269 min read
waylandlinuxx11text-expandergnomekdexwaylandinput
Share:
Text Expansion on Wayland: Why It Breaks and What Actually Works

Quick answer: Text expanders need to watch every keystroke system-wide and simulate typing into whatever app has focus. X11 allowed both by default; Wayland's compositors deliberately restrict both for security reasons, which is why a text expander that works perfectly on Ubuntu 20.04 can install cleanly and do absolutely nothing on a modern Wayland session — with no error message. There's no single fix; the real options are XWayland (run the old way, inside a compatibility layer), an evdev/uinput backend with explicit input-group access, or a dedicated low-level input backend that asks for a one-time permission grant. Lightning Assist uses the latter.

If you've installed a text expander, typed your trigger, and watched nothing happen — no error, no crash, just silence — you're very likely on Wayland, and this is a known category of problem, not a bug specific to whatever tool you picked.

Why Wayland Blocks Global Key Listening

On X11, any process can register a low-level keyboard hook and read every keystroke on the system, and any process can simulate keypresses into whatever window currently has focus — that's literally what tools like xdotool do, and it's why text expanders, hotkey managers, and remote-control software have worked on Linux for two decades without much friction. It's also, from a security standpoint, exactly the kind of thing you don't want by default: any application, including a compromised one, can log your keystrokes or inject arbitrary input into your banking session.

Wayland's compositors (Mutter for GNOME, KWin for KDE Plasma, wlroots-based ones for Sway and similar) were designed around the opposite default: an application only sees the input events destined for its own window, and nothing can inject synthetic input into another application without an explicit, deliberate mechanism for doing so. This isn't an oversight or a missing feature — it's the security model working as intended. The cost is that every tool which depended on X11's "any process can watch and inject" behavior needs a different, and usually more limited, way to do the same job.

The practical result: a text expander that hooks keystrokes the X11 way sees nothing on a pure Wayland session, and a text expander that injects text the X11 way has nothing to inject into. It typically fails silently rather than with a clear error, because there's no exception being thrown — the events it's listening for simply never arrive.

Why Browser Extensions Don't Cover the Desktop

A natural workaround is a browser-extension-based text expander, and for browser tabs alone, it works — extensions operate inside the page's DOM, which has nothing to do with Wayland's input model. The problem is scope: an extension only ever sees the browser it's installed in. It cannot expand a snippet in your terminal, your IDE, a native GTK or Qt application, Slack's or Discord's desktop client, or a PDF reader. If your day involves anything outside a browser tab — which for developers and support teams is most of the day — a browser extension solves a fraction of the problem and leaves the rest of your desktop uncovered.

What Actually Exists on Wayland Today

There's no universal fix, but there are a handful of real, documented approaches, each with trade-offs.

XWayland — running the old way, inside a compatibility layer

Most Wayland desktop environments (GNOME, KDE Plasma out of the box on Ubuntu 22.04+, Fedora 38+, and similar) run XWayland alongside the native Wayland compositor — a compatibility layer that lets X11-only applications keep working. A tool built on X11 input hooks continues to work for applications running inside XWayland. The catch is scope: if you're in a session where XWayland is explicitly disabled (some hardened GNOME configurations), or the specific application you're typing into is a native Wayland client rather than an XWayland one, X11-style hooking doesn't reach it.

The zwp_virtual_keyboard_v1 protocol

Some Wayland compositors — GNOME's Mutter and KDE's KWin among them — implement the zwp_virtual_keyboard_v1 Wayland protocol, which gives an application a sanctioned way to simulate keyboard events. This is closer to a built-in, protocol-level answer than a workaround, but it's compositor-dependent: an app that relies on it works only where the compositor has chosen to implement that protocol, and behavior can still vary — some setups fall back to a clipboard-paste substitute, which can behave differently in apps with special paste handling (a terminal with bracketed-paste mode, for instance).

xdg-desktop-portal's RemoteDesktop interface

The freedesktop.org portal specification defines a RemoteDesktop interface built explicitly to "allow remote controlling a desktop session" — it can inject keyboard and pointer events, but only after the user grants KEYBOARD/POINTER access when the session starts, and it's a permission-scoped session mechanism rather than an always-on system hook. It's the sanctioned door Wayland provides for input injection, but it was designed around remote-control and screen-sharing tools, not around "silently detect every trigger I type, forever, in the background" — which is what a text expander actually needs.

evdev/uinput with input-group access

The lower-level option is reading raw input directly from /dev/input (evdev) and injecting synthetic events through /dev/uinput, bypassing the compositor's input model entirely. This is genuinely cross-compositor — it doesn't care whether you're on GNOME, KDE, or Sway, because it operates below all of them, at the kernel input layer. Espanso uses exactly this approach for its Wayland support, which its own documentation describes as "currently experimental": it requires a one-time setcap cap_dac_override+p grant on the binary (or membership in the input group, depending on setup) to read raw input without running as root, and it comes with known caveats — non-US keyboard layouts need explicit configuration, GNOME sessions can show clipboard-backend flicker, and connecting a new keyboard requires a manual restart of the service. It works, but "experimental" is the right word for where it stands today.

Tools that simply don't support Wayland

Some Linux automation tools are built directly on xdotool and the X11 window tree, with no Wayland path at all — AutoKey is the clearest example: it's X11-only, and XWayland doesn't help because its input simulation targets the X11 window tree directly, not the compositor. If you're on a pure Wayland session, tools like this simply don't work, full stop, regardless of configuration.

How Lightning Assist Handles It

Lightning Assist takes a two-path approach depending on session type. On X11 and on XWayland sessions, it uses standard X11 input hooks — the same mechanism that's worked reliably on Linux for years. On a pure Wayland session, it switches to a dedicated low-level input backend: the first time it needs it, the app asks once for input access (a "Grant access" prompt), and after that single grant, global key detection and text expansion work the same way across GNOME, KDE, and other compositors — no YAML, no setcap command to run yourself, no per-keyboard-layout configuration step. This is a maintained backend built for the purpose, not a fallback bolted on afterward, and the one-time grant model means you don't repeat a manual step every session.

A Practical Checklist Before You Pick a Tool

Given how much variation exists between tools, it's worth checking a few things before you commit to one on a Wayland desktop:

  • Does it document Wayland support explicitly, or only claim "Linux support" broadly? Broad claims often mean "tested on X11" with Wayland behavior untested.
  • Does it need a manual setcap or root step to work on Wayland? Not a dealbreaker, but you should know that going in rather than discovering it after installation.
  • Does it name specific compositor caveats (GNOME, KDE, Sway) rather than a blanket "works on Wayland"? Tools that are honest about compositor-specific quirks (clipboard flicker, keyboard-layout config, restart-on-new-device) are usually the ones that have actually been tested there.
  • Does XWayland need to stay enabled? If a tool only works through XWayland, confirm your desktop environment has it on by default (most do) before assuming compatibility.

Frequently Asked Questions

Why does my text expander work on one Linux machine but not another?

The most common cause is session type: X11 sessions and Wayland sessions handle global input completely differently, and a tool built primarily around X11 input hooks can work flawlessly on one and do nothing on the other. Run echo $XDG_SESSION_TYPE in a terminal to check which session type you're currently running.

Is Wayland just broken for productivity tools?

No — it's a different, more restrictive security model, not a bug. The restrictions that block naive global-input tools are the same restrictions that make it harder for a malicious app to log your keystrokes or inject input into your banking session. The tools that work well on Wayland are the ones built specifically around its permission model (portals, zwp_virtual_keyboard_v1, or a dedicated evdev/uinput backend with input-group access) rather than ones assuming X11-style unrestricted access.

Does disabling XWayland break text expansion?

It can, for any tool relying on X11-style hooks to reach XWayland-run applications. If you're on a hardened setup with XWayland explicitly disabled, check specifically whether your text expander has a native-Wayland backend (not just an X11 hook) — Lightning Assist's dedicated Wayland input backend and Espanso's experimental evdev/uinput mode are both built for exactly this case; a tool built purely on xdotool or X11 window-tree access, like AutoKey, is not.

Do I need to run any terminal commands to get Wayland support working?

It depends on the tool. Espanso's Wayland mode needs a one-time setcap grant (or equivalent input-group membership) that you run yourself. Lightning Assist's Wayland backend instead prompts for a one-time in-app "Grant access" permission the first time it's needed — no terminal command required.

Related Reading

Sources

Related Articles