Espanso Not Working on Windows 11? What to Check

When Espanso stops expanding on Windows 11, check four things in this order: whether Espanso is running, whether a YAML file has an error, whether the app you are typing in runs as administrator, and whether that app pastes the way Espanso expects. Start with one test: type :espanso in Notepad. If it turns into “Hi there!”, Espanso works and the problem is the other app.

The :espanso match ships in the default match/base.yml, as the Getting Started guide shows. If you have deleted it, use any simple match of your own that you know is correct.

Espanso is not running

On Windows, a running Espanso shows an icon in the notification area. If it is not there, start Espanso from the Start menu. In the portable version, run START_ESPANSO.bat, as the Getting Started guide says.

To check from a terminal, run espanso status. The command-line reference lists the other commands you need here: espanso start, espanso restart and espanso log.

Two installation details catch people out:

• Espanso does not run on ARM processors yet. The Windows installation page says it runs on Windows 10 or later, “currently only on x64 architecture”, and that ARM support is planned.
• Windows SmartScreen may block the installer. The same page explains that Espanso’s digital signature is still relatively new. Download Espanso only from espanso.org or one of the package managers that page names: winget, Chocolatey or Scoop.

A YAML error stopped your matches

Espanso keeps every match in YAML files, and the format is strict about spaces. The Getting Started guide puts it in bold: keep the indentation, or the file is not valid YAML and the trigger will not work. It also recommends spaces rather than tabs.

Your files are in %AppData%\espanso by default, with matches in match\base.yml. If you are not sure where yours are, run espanso path; the configuration basics list the defaults for each system.

This match breaks because the second line lost its indentation:

matches:
  - trigger: ":sig"
  replace: "Best regards,\nAnna"

This one works:

matches:
  - trigger: ":sig"
    replace: "Best regards,\nAnna"

Quotes matter too. The match basics say that text containing \n or \t, or starting with a YAML special character such as ', [, {, *, &, !, %, # or @, must be in quotes. Espanso reloads the configuration when you save a file. If your match still does not work, run espanso log and look for the file and line that failed to load.

One app does not expand

If :espanso works in Notepad, Espanso is fine. Look at the app where it fails.

The app runs as administrator

Windows does not let an ordinary app send keystrokes into a window running with higher rights. Microsoft’s SendInput documentation states that applications may “inject input only into applications that are at an equal or lesser integrity level”. Espanso’s issue tracker has an open report, #2388, about exactly this case. The same rule applies to every text expander that runs without administrator rights; the guide to expansion that fails in one app covers it in more detail.

The safe fix is to open that app normally if it does not need administrator rights. Running Espanso itself as administrator also works, but it gives administrator rights to a program that sees every keystroke. Decide that deliberately, and on a work PC ask IT first.

The app pastes with a different shortcut

Espanso inserts text in two ways: by simulating key presses or through the clipboard. By default it decides for itself, and according to the options reference any match longer than 100 characters goes through the clipboard with Ctrl+V. In an app that pastes with a different shortcut, short matches work and long ones do not. The reference adds that Espanso already ships built-in patches that change the paste shortcut for some apps.

Fix it for that app only, with an app-specific configuration. Create a file in the config folder, for example config\exampleapp.yml:

filter_exec: ExampleApp
paste_shortcut: CTRL+SHIFT+V

Replace ExampleApp with part of the app’s executable path, and the shortcut with the one that app uses to paste. The alternative is backend: Inject in the same file, which makes Espanso type every match key by key instead of pasting.

Old clipboard text appears instead of the match

Espanso copies the match to the clipboard, waits, and then pastes. If the app pastes before the copy has finished, you get whatever was on the clipboard before. The options reference describes this case and the fix: increase pre_paste_delay (300 ms by default). Try 500 for that app first.

If characters go missing or the trigger is not fully deleted, the same page suggests raising key_delay or inject_delay, but notes they have little effect on Windows. There, try switching the backend for that app instead.

Layouts and shortcuts

Expansion stops after you switch keyboard layout

Espanso caches the active layout on Windows for up to 2,000 ms by default. The options reference suggests lowering win32_keyboard_layout_cache_interval if you switch often and see detection drop out.

Alt+Space opens the wrong window

Espanso’s search bar uses Alt+Space by default, and so does PowerToys Run. Change one of them: in Espanso, set search_shortcut in config\default.yml.

Espanso switches itself off

Before version 2.1.2, double-pressing Alt toggled Espanso off, and the options reference calls this a major source of confusion. Current versions ship with toggle_key off. If an old configuration still sets it, remove the line or set it to OFF.

When the YAML keeps breaking

Espanso is actively developed: version 2.4.1 was released on 2 September 2026. It is free and open source under GPL-3.0, runs on Windows, macOS and Linux, and has forms, regex triggers and a package hub. If you use those, fix the configuration and stay.

If you only need a short trigger to become a fixed piece of text, and the YAML is what keeps breaking, a tool with a settings window does the same job with nothing to indent. The guide to text expansion without YAML or a subscription explains that approach. Text Replacements is one such tool: you add a shortcut and its text in a window, expand it with Space, Tab or Enter, and import a CSV file if you have many. It has none of Espanso’s forms, scripts or regex triggers, and it runs only on Windows.

Frequently asked questions