// troubleshooting guide · espanso
Espanso Not Working on Wayland
- Status
- Workaround available
- platforms:
- Linux (Wayland)
- updated:
- November 15, 2026
- reports:
- 4
- Method
- how we research
RUNBOOK · espanso/wayland4 FIXES
// quick answer
Wayland support is experimental. Install the Wayland build, give the binary CAP_DAC_OVERRIDE, set your keyboard layout, and start it.
Most likely fix: Confirm the session and build
How to fix it
// try these in order, the most common fix is first
FIX 1Confirm the session and build
- 01Run `echo $XDG_SESSION_TYPE`
- 02Install the Wayland package (DEB, Terra RPM) or compile from source on Arch
Did this fix it?FIX 2Grant input access
- 01Run `sudo setcap "cap_dac_override+p" $(which espanso)`
- 02Run `espanso service register` then `espanso start`
Did this fix it?FIX 3Set the keyboard layout
- 01Open config/default.yml
- 02Add `keyboard_layout:` with `layout: "it"` (use your layout code)
- 03Run `espanso restart`
Did this fix it?FIX 4Try running unmanaged
- 01Run `espanso start --unmanaged` or `espanso-wayland start --unmanaged` if the service times out
Did this fix it?
Symptoms
Espanso starts but does not expand, or fails to start with a timeout or EVDEV error.
Why it happens
- C-01X11 build installed on a Wayland session
- C-02Missing capability for /dev/input and /dev/uinput
- C-03Keyboard layout not set for non-US keyboards
- C-04systemd service failing on some distros
// this guide also covers
- espanso wayland
- espanso wayland not working
- espanso fedora wayland
Still not working?
If Espanso keeps failing, you're not alone. See every Espanso problem users report or the alternatives people switch to.
Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.
Talk to us