espanso: a local text expander for Windows, macOS and Linux

What espanso replaces, and who ends up using it

A text expander watches what you type and substitutes something else when a keyword appears. espanso does this system-wide, so the same trigger works in an editor, a browser field, a chat client or a terminal. The README lists the intended uses plainly: expanding common sentences, keeping code snippets available everywhere, running custom scripts, inserting emojis, and building a personal autocorrect that applies outside any single application.

The audience is narrower than "everyone who types". espanso is configured through YAML files on disk, so it appeals to people who already keep dotfiles in version control and want snippets to move with them. The README describes the configuration as file based and the program as 100% local with no tracking. That combination matters to anyone who cannot paste internal identifiers, customer names or boilerplate into a hosted snippet service. There is no account, and the README does not describe any network feature beyond the package manager that fetches packages from espanso hub.

The trade-off is visible in the same list. There is no graphical match editor in the README's feature set. Editing snippets means editing YAML, and the README warns readers to adhere to proper YAML spacing, which tells you the failure mode is a parse error rather than a helpful dialog.

How the trigger-to-text pipeline is wired

The workspace in Cargo.toml splits the program into crates whose names map onto the pipeline. espanso-detect observes input, espanso-match decides whether a trigger fired, espanso-render produces the replacement text, and espanso-inject writes it into the focused application. Around those sit espanso-config for loading and validating YAML, espanso-engine to coordinate the sequence, espanso-clipboard and espanso-ipc for moving data between processes, espanso-ui for the search bar and other windows, and espanso-package for the hub package manager.

That separation is why the project can claim cross-platform behaviour without three separate codebases. The platform-specific work is pushed to the edges. The README credits libxdo and xclip for the Linux port, and libxkbcommon with wl-clipboard for the Wayland port, which is consistent with detection and injection being the parts that touch the operating system directly. The core matching and rendering logic stays in Rust and does not care which desktop it runs on.

One consequence is worth stating. Because injection happens at the system input layer rather than inside an application, espanso works with almost any program, as the README puts it, but it also means correctness depends on the target application accepting synthetic input or clipboard pastes. Applications that block or mangle that path are the ones where expansion will misbehave, and the README does not enumerate them.

Installing espanso and writing a first match

The README points to espanso.org for downloads and to the official documentation for setup instructions, and it does not reproduce per-platform install commands. On Linux the repository ships a snapcraft.yaml and a snap/ directory, so a snap build is part of the project's own packaging, but treat the website as the authoritative source for the current command on your distribution.

What the README does give is the shape of a match file. Matches live in YAML files, and you can create additional files to organize them however you like. A minimal file looks like this:

matches:
  - trigger: ":hello"
    replace: "Hi There!"
  - triggers: [":test1", ":test2"]
    replace: "These both expand to the same thing"

The first entry fires when you type :hello and substitutes Hi There!. The second shows that a single entry can carry several triggers through the plural triggers key, so :test1 and :test2 both produce the same replacement. After saving the file, typing the trigger in any application should produce the replacement text.

Where the files live depends on your platform. The official documentation covers the configuration directory layout; the README itself does not list the paths. If you plan to keep matches in version control, confirm the location from the docs on each machine before symlinking anything into it.

The limitations that decide whether espanso fits

Wayland support is the clearest constraint. The README labels it experimental, and the underlying implementation depends on libxkbcommon and wl-clipboard. On a Wayland session you should expect the expansion path to be less settled than on X11, Windows or macOS, and the README offers no compatibility matrix for compositors.

Configuration errors are another failure mode with no safety net. Matches are YAML, and the README's only guidance is to adhere to proper YAML spacing. A malformed file is a text file, not a validated schema, so the feedback you get depends on how the loader reports the problem rather than on an editor that refuses to save. The schemas/ directory in the repository suggests schema definitions exist for editors that consume them, but the README does not describe how to wire those up.

There is also a scope limit that is easy to miss. espanso is a desktop program. The README lists Windows, macOS and Linux as the supported platforms and says nothing about mobile, so anyone hoping for the same triggers on a phone is looking at the wrong tool. Finally, expansion happens in whatever field has focus. If you expect triggers to be ignored in password fields or on specific sites, the README does not promise that, and app-specific configuration is the mechanism it offers instead.

espanso against a built-in snippet manager

The obvious alternative is the snippet feature already inside your editor or operating system. VS Code, JetBrains IDEs and macOS text replacement all expand triggers, and they cost nothing extra to enable. The difference is reach. Editor snippets stop at the editor window, and system text replacement on macOS is limited to plain text substitutions with no script execution, no image insertion and no package manager. espanso's README claims system-wide operation across almost any program, plus shell commands, custom scripts, images, dates and forms.

The second alternative is a hosted snippet service with a browser extension and team sharing. Those give you a GUI, sync across devices and a mobile client. espanso gives you none of those, and in exchange it keeps every match on local disk with no tracking, as the README states. If your snippets contain anything you would not paste into a third-party web form, that exchange is the whole argument.

The third is writing your own auto-replace script with xdotool or a keyboard remapper. That is feasible on one platform and miserable across three, which is exactly the surface espanso already covers with its detect, match, render and inject crates.

Maintenance, upgrades and the GPL-3.0 question

The repository is not archived, and the last push was on 2026-09-20. Releases are not frequent: v2.3.0 shipped on 2025-10-11, v2.4.0 on 2026-07-21 and v2.4.1 on 2026-09-02. That cadence suggests a project in maintenance-and-fixes mode rather than one adding large features every month, which is reasonable for a tool whose job is to sit quietly in the background.

Upgrade cost is mostly your own configuration. Matches are plain YAML files that you own, and the README's example uses the current trigger, triggers and replace keys, so there is no database migration to worry about. The risk sits in packages: the built-in package manager pulls from espanso hub, and a package you install can be updated independently of the core binary. Pin or review what you install if the snippets matter.

On licensing, espanso is GPL-3.0. For ordinary use, installing and running the binary costs you nothing and imposes no obligation on your own work. The obligation appears if you distribute a modified version of espanso, because the GPL requires derivative distributions to carry the same licence. This is a description of the licence's terms, not legal advice; if you intend to ship a modified espanso inside a product, have a lawyer read the GPL-3.0 text rather than relying on a summary.

Editorial conclusion

Adopt espanso if you want file-based snippets that work across Windows, macOS and Linux and never leave your machine. Do not adopt it if you need a graphical match editor, native Wayland support, or a mobile client. Before rolling it out, check that your desktop session is X11 or that you accept the experimental Wayland path, and read the GPL-3.0 terms if you plan to redistribute a modified build.

Frequently asked questions

Official sources

1. espanso/espanso on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases