# Espanso Problems & Issues 2026 - Not Working, Wayland, macOS

Source: https://www.tryorbye.com/products/espanso
Last analyzed: 2026-11-15
Try or Bye score: 64/100

## Verdict: Try with caution

Espanso works for some teams, but users report recurring problems (score 64/100). Most reported issues: Espanso on Wayland is experimental and hard to set up; Espanso expansions stop working until you restart it; YAML config is a barrier for non-technical users. Not a good fit for: Non-technical teams sharing snippets; Mobile-first users. Users most often switch to TextExpander, Alfred, Raycast.

## What it is

Espanso is a free, open-source text expander written in Rust for Windows, macOS and Linux. Snippets are YAML files with support for regex, forms, scripts and app-specific configs. Best for technical users who want local, scriptable text expansion.

## Common errors & fixes

### Espanso App-Specific Config Not Working

Filters are case-sensitive regexes and only one config applies. Use #detect# to get the right values, and note Wayland does not support them.

1. **Detect real values** — Open the app and type `#detect#` (needs v2.1.1+) Copy exec or class into filter_exec or filter_class
2. **Fix priority** — Rename files so the intended one sorts first Avoid filter_title for changing titles
3. **Wayland** — On KDE install kdotool for partial support Otherwise use global options

Full guide: https://www.tryorbye.com/products/espanso/issues/app-specific-config-not-working

### Espanso Long Text Not Inserting

Replacements over 100 characters are sent via the clipboard. Raise clipboard_threshold or set the backend explicitly.

1. **Raise the threshold** — Open config/default.yml Set `clipboard_threshold: 500` Run `espanso restart`
2. **Force the backend** — Set `backend: clipboard` or `backend: Inject` globally or per app
3. **Tune delays** — Increase `inject_delay` if the app drops characters

Full guide: https://www.tryorbye.com/products/espanso/issues/long-text-not-inserting

### Espanso macOS Accessibility Permission Not Working

On macOS, Espanso needs Accessibility permission. If it is set but nothing expands, remove and re-add the entry and restart Espanso.

1. **Re-grant permission** — Open System Settings > Privacy & Security > Accessibility Remove Espanso with the minus button Run `espanso start` and add it again when prompted, switch it on
2. **Restart the service** — Run `espanso restart` Run `espanso status` to confirm it is running
3. **Follow the macOS install steps for the security warning** — Open the app once from Applications Approve it in Privacy & Security if blocked

Full guide: https://www.tryorbye.com/products/espanso/issues/macos-accessibility-permission

### Espanso Not Expanding Text

Espanso is running but triggers do nothing. First restart it, then test with force_mode to find out whether the keys or clipboard backend works.

1. **Check and restart the service** — Run `espanso status` Run `espanso restart` Run `espanso log` to look for errors
2. **Test both backends** — Add `force_mode: clipboard` to one match, save, and test If that fails try `force_mode: keys` Set the working one as `backend:` in config/default.yml
3. **Check the trigger rules** — Remove `word: true` while testing Make sure the trigger is not preceded by letters

Full guide: https://www.tryorbye.com/products/espanso/issues/not-expanding

### Espanso Won't Start

If Espanso times out or fails to start, check the service registration and input permissions, then try unmanaged mode.

1. **Reset the service** — Run `espanso service register` Run `espanso start`
2. **Run unmanaged** — Run `espanso start --unmanaged`
3. **Linux permissions** — Apply setcap as in the Wayland guide
4. **Check logs** — Run `espanso log`

Full guide: https://www.tryorbye.com/products/espanso/issues/not-starting

### Espanso Not Working in Obsidian or VS Code

Editors and Electron apps interfere with injection. Use an app config switching backend to clipboard and adjust delays.

1. **Add app config** — Use #detect# to get exec/class Set `backend: clipboard`
2. **Adjust delays** — Raise `inject_delay`

Full guide: https://www.tryorbye.com/products/espanso/issues/obsidian-vscode-issues

### Espanso Secure Input Stuck on Mac

When Secure Input is stuck macOS blocks Espanso everywhere. Restart the password manager and browser, or log out and in.

1. **Restart likely culprits** — Quit and reopen your password manager Restart the browser if it has a password extension
2. **Run auto-fix** — Click the Espanso menu bar icon Choose Launch SecureInput auto-fix (may need Automation permission, experimental and likely only for older macOS)
3. **Find the app** — Quit apps one by one until the normal icon returns
4. **Reset** — Log out and back in

Full guide: https://www.tryorbye.com/products/espanso/issues/secure-input-mac

### Espanso Stops Working After Sleep

If expansion dies after resume, restart the service. Keep auto_restart on and restart after plugging in a keyboard.

1. **Restart** — Run `espanso restart`
2. **After new hardware** — Run `espanso restart` after connecting a keyboard
3. **Report** — Include `espanso log` in a GitHub issue

Full guide: https://www.tryorbye.com/products/espanso/issues/stops-after-sleep

### Espanso Wrong Characters in Terminal

Terminals paste differently. Use an app-specific config with a different backend or paste_shortcut for the terminal.

1. **Create a terminal config** — Run `espanso path` to find the config folder Create config/terminal.yml with a filter_exec or filter_class Use #detect# in the terminal to find the values
2. **Change paste shortcut** — Add `paste_shortcut: CTRL+SHIFT+V` (or SHIFT+INSERT) and `backend: clipboard`
3. **Try Windows Terminal** — Use Windows Terminal instead of the legacy console on Windows

Full guide: https://www.tryorbye.com/products/espanso/issues/terminal-wrong-characters

### Espanso Not Working on Wayland

Wayland support is experimental. Install the Wayland build, give the binary CAP_DAC_OVERRIDE, set your keyboard layout, and start it.

1. **Confirm the session and build** — Run `echo $XDG_SESSION_TYPE` Install the Wayland package (DEB, Terra RPM) or compile from source on Arch
2. **Grant input access** — Run `sudo setcap "cap_dac_override+p" $(which espanso)` Run `espanso service register` then `espanso start`
3. **Set the keyboard layout** — Open config/default.yml Add `keyboard_layout:` with `layout: "it"` (use your layout code) Run `espanso restart`
4. **Try running unmanaged** — Run `espanso start --unmanaged` or `espanso-wayland start --unmanaged` if the service times out

Full guide: https://www.tryorbye.com/products/espanso/issues/wayland

### Espanso Not Triggering on Windows

On Windows 11 test force_mode and key delays, and check Espanso is running with the same privileges as the target app.

1. **Check status** — Run `espanso status` and `espanso restart`
2. **Test modes** — Try `force_mode: keys` then `clipboard`
3. **Tune timing** — Raise `key_delay` or `inject_delay` in config/default.yml

Full guide: https://www.tryorbye.com/products/espanso/issues/windows-not-triggering

### Espanso YAML Config Error

Most config errors are indentation or unquoted special characters. Quote strings with \n, \t or leading special characters and check the log.

1. **Read the error** — Run `espanso log` Fix the file and line named
2. **Quote values** — Wrap strings with newlines, tabs or leading special characters in quotes Use `|` for multi-line text
3. **Validate** — Use spaces only, then `espanso restart`

Full guide: https://www.tryorbye.com/products/espanso/issues/yaml-config-error

## Common problems

- **Espanso on Wayland is experimental and hard to set up** (onboarding): Wayland support is labelled experimental in the official docs. It needs a Wayland-specific build (not available as a package on every distro), a setcap step for input device access, and a keyboard layout set by hand for non-US layouts.
- **Espanso expansions stop working until you restart it** (reliability): Users report the service still showing as running while triggers no longer expand, often after sleep or resume, until `espanso restart` is run. Most reported on Linux and Wayland but also seen elsewhere.
- **YAML config is a barrier for non-technical users** (usability): Everything is configured by hand in YAML files. Indentation and quoting mistakes break matches, and there is no built-in visual editor, which is the main reason people pick TextExpander or Text Blaze instead.
- **Espanso not expanding in terminals and some apps** (reliability): Terminals (Kitty, Windows console host), Obsidian and Electron apps are reported as trouble spots: dropped characters, wrong special characters or nothing happening. Switching backend or paste shortcut per app usually fixes it.
- **Espanso stops on macOS when Secure Input is stuck** (security): On macOS, Secure Input (turned on by password fields, and often left on by password managers or browser extensions) blocks all expansion. The official docs call it unreliable and say the auto-fix only works on older macOS versions.
- **macOS accessibility permission confusion after install or update** (onboarding): Espanso needs Accessibility permission on macOS. Users report it not sticking after updates or reinstalls, and having to remove and re-add the entry, plus a security warning on first start.
- **Espanso fails to start on Fedora and other Wayland setups** (reliability): Reports of 'unable to start service: timed out' and EVDEV permission errors on Fedora KDE, where only running the Wayland binary directly worked and systemd service mode did not.
- **Long replacements silently fail (clipboard_threshold)** (usability): Replacements over 100 characters switch to clipboard injection by default. In some setups this fails with no warning, so long snippets do nothing until clipboard_threshold or backend is changed.
- **No mobile apps and no built-in sync** (integrations): Espanso runs on Windows, macOS and Linux only. There is no iOS or Android app and no cloud sync, so snippets travel only via git, Dropbox or similar.
- **Support is community only with a large open issue backlog** (support): Help comes from GitHub issues, Discussions and Reddit. The repository carries around 546 open issues, and some threads end without a documented fix.
- **App-specific configs are not supported on Wayland** (customization): Per-app configuration (filter_title, filter_exec, filter_class) does not work on Wayland, apart from a partial workaround on KDE with kdotool. This removes the usual fix for apps that misbehave.
- **Free and open source, but expect time cost** (pricing): Espanso is GPL-3.0 and free, with donations only. The cost is setup and troubleshooting time rather than money.
- **Keyboard layout and new keyboards confuse Espanso** (integrations): Non-US layouts on Wayland need layout set in default.yml, and a newly connected keyboard is only picked up after restarting Espanso.

## What users like

- **Free and open source (GPL-3.0)**: No subscription, no account, no tracking by the vendor. Code is public on GitHub with about 14.8k stars.
- **Very powerful matches**: Regex triggers, forms, date expansion, shell commands and scripts, app-specific configs and variables go well beyond a basic snippet tool.
- **Plain-text config you can version**: Snippets are YAML files, so they can be stored in git, shared between machines and edited with any editor.
- **Cross-platform: Windows, macOS, Linux**: Same config format across the three desktop systems, plus a package hub for installing ready-made snippet sets.
- **Fast and lightweight (written in Rust)**: Small background process, system-wide expansion without per-app plugins.
- **Local-only, privacy friendly**: Snippets stay on your machine, nothing is sent to a cloud service.

## Pricing

- **Espanso (free, open source)**: $0.00 (free) — hidden costs: Setup time; Wayland needs manual setup; donations optional

## Who should and shouldn't use it

- **Developers and sysadmins** — Good fit: Comfortable with YAML, wants snippets in git and shell-powered expansions.
- **Linux X11 users** — Good fit: Best-supported Linux setup, with DEB and AppImage packages.
- **Privacy-minded users** — Good fit: Local, open source, no account.
- **Power users who like regex and scripts** — Good fit: Regex triggers, forms and script variables are strong.
- **Non-technical teams sharing snippets** — Avoid: No GUI or team sharing; TextExpander or Text Blaze fit better.
- **Linux Wayland users** — Depends: Works but experimental; expect setup work and no app-specific configs.
- **Mobile-first users** — Avoid: No iOS or Android app.
- **macOS users wanting zero setup** — Depends: Works, but needs Accessibility permission and can hit Secure Input.

## Alternatives

- **TextExpander** (https://www.tryorbye.com/products/textexpander): Polished GUI, team sharing and sync across Mac, Windows and iOS. Trade-off: paid subscription and not open source.
- **Alfred** (https://www.tryorbye.com/products/alfred): Snippets built into the Mac launcher with a GUI (Powerpack required). Trade-off: macOS only and paid.
- **Raycast** (https://www.tryorbye.com/products/raycast): Snippets inside a Mac launcher with a clean UI. Trade-off: macOS-centric, some features paid.
- **Microsoft PowerToys** (https://www.tryorbye.com/products/powertoys): Free from Microsoft with Keyboard Manager and Advanced Paste, but no true snippet expansion. Windows only.
- **AutoHotkey** (https://www.tryorbye.com/products/autohotkey): Windows hotstrings with full scripting. Trade-off: scripting language, Windows only.
- **Beeftext**: Free open-source text expander for Windows with a GUI. Trade-off: Windows only, less powerful.
- **Text Blaze** (https://www.tryorbye.com/products/text-blaze): Browser-based snippets with team sharing. Trade-off: mainly works in the browser.
- **Typinator**: Mac-native expander with a GUI. Trade-off: paid and Mac only.

## FAQ

### Is Espanso free?

Yes. Espanso is open source under GPL-3.0 and costs nothing. The project accepts donations but there is no paid tier.

### Is Espanso worth it?

If you are comfortable editing YAML and want a free, scriptable text expander, yes. If you want a GUI, sync and team sharing, a paid tool like TextExpander is a better fit.

### Why is Espanso not working?

Check `espanso status`, restart with `espanso restart`, then test a trigger with force_mode: clipboard or keys. On macOS check Accessibility permission and Secure Input; on Linux check X11 vs Wayland.

### Does Espanso work on Wayland?

Support is experimental. You need the Wayland build, the CAP_DAC_OVERRIDE capability on the binary, and a keyboard layout set in default.yml for non-US keyboards. App-specific configs do not work.

### Why does Espanso not work in password fields on Mac?

macOS Secure Input blocks all apps from reading keystrokes in sensitive fields. It can also get stuck because of a password manager or browser extension.

### Does Espanso have a GUI?

No graphical snippet editor. Config is YAML files; there is a search bar and a system tray icon, and a package hub for ready-made packs.

### Is there an Espanso app for iPhone or Android?

No. Espanso runs on Windows, macOS and Linux only.

### Espanso vs TextExpander: which is better?

Espanso is free, open source and more scriptable. TextExpander has a GUI, sync, team sharing and mobile apps but is a paid subscription.

### How do I sync Espanso snippets between computers?

There is no built-in sync. Keep the config folder (see `espanso path`) in git or a synced folder like Dropbox.

### Why does Espanso not expand long text?

Replacements over 100 characters use the clipboard by default (clipboard_threshold). Raise the value or set backend: clipboard and restart Espanso.

### Where is the Espanso config file?

Run `espanso path` to print the config folder. Matches live in match/base.yml and global options in config/default.yml.

### Is Espanso safe?

It is open source and runs locally with no cloud service. Like any tool that watches keystrokes system-wide it needs input permissions, so install only from official sources.

### How do I stop Espanso expanding inside a word?

Add word: true to the match so it only triggers between word separators.

---
Try or Bye aggregates problem patterns from user reviews, forums, and app stores. Methodology: https://www.tryorbye.com/methodology