Espanso: What It Is and How to Get Started with Text Expansion

What it is

Espanso is an open-source, cross-platform text expander created by Federico Terzi and written in the Rust programming language. A text expander is a utility that runs in the background, listens for designated keywords as they are typed, and immediately swaps them out for expanded content. Instead of manually retyping lengthy email replies, boilerplate paragraphs, or complex technical snippets, users designate brief trigger abbreviations that the application transforms into full text.

The project is developed with a privacy-first architecture. It functions completely locally on the host machine, meaning it operates without background tracking or remote telemetry monitoring user keystrokes. While initially developed by Federico Terzi, the project is maintained by a small core team that includes Federico Terzi, Archigos, lead maintainer Auca, n8henrie, and smeech, alongside a broader group of open-source contributors.

Espanso relies on a file-based configuration philosophy inspired by Unix conventions. Settings, expansion rules, and templates are stored in straightforward YAML text files rather than locked behind proprietary databases. This design makes configurations transparent, modular, and easy to edit or replicate across different machines.

What it can do

At its core, Espanso is designed to reduce repetitive typing across virtually any desktop application. Its core mechanism revolves around the concept of a “match,” which establishes a direct connection between an input cause (the trigger keyword) and an output effect (the replacement text or action).

Espanso supports a wide variety of expansion and automation capabilities:

• Basic and Multi-Trigger Expansions: Triggers are defined as simple strings, such as :date, e', signature, or >>up. Multiple distinct triggers can also be assigned to produce the exact same replacement text.
• System-Wide and App-Specific Profiles: Expansions work across desktop text fields by default, but configurations can also be customized for individual applications. Users can set filters so specific snippet files load only in dedicated software (such as code editors like Visual Studio Code) or disable specific expansions (such as emojis) in communication tools like Slack.
• Dynamic Scripts and Shell Commands: Beyond plain text, replacements can execute custom scripts and shell commands, allowing users to inject dynamic outputs into their documents.
• Forms and Interactive Variables: Espanso supports forms, which let users supply dynamic input fields and variables before inserting text.
• Date Expansion: Dynamic current date values can be inserted automatically through configured triggers.
• Images and Emojis: The software can expand keywords into graphical images as well as emoji characters.
• Regex Triggers: Users can define pattern-based triggers utilizing regular expressions to handle flexible expansion rules.
• Built-in Search Bar: When users forget a specific trigger string, they can open an interactive search bar using a keyboard shortcut (ALT+SPACE on Windows and Linux, or Option+Space on macOS) or via the status bar icon. Typing > at the start of the search bar exposes built-in control and reporting commands.
• Safety and Control Options: A backspace-undo feature is available to immediately revert an unwanted expansion and restore the typed trigger if Backspace is pressed right after replacement occurs. Users can also configure a dedicated toggle key or menu toggle to pause expansion.
• Package Management via Espanso Hub: Through its integrated package manager and the public Espanso Hub, users can install shared packages (such as prebuilt emoji dictionaries) or publish their own packages for others to use.

According to the project README, the tool delivers fast and reliable performance due to its Rust codebase.

How to get started

Getting started with Espanso involves verifying that the background process is running, testing the default trigger, and learning how to define custom match rules.

Verifying the Service

Once installed, check whether Espanso is active:

• On Windows and macOS, look for the Espanso icon in the system tray or menu bar status area.
• On Linux, open a terminal window and check the process status by running:

espanso status

If the software is not running:

• Windows: Open Espanso from the Start Menu, or execute START_ESPANSO.bat if using the portable version.
• macOS: Launch the application from the Applications folder (authorizing any operating system security prompts that appear).
• Linux: Start the background daemon by running:

espanso start

Testing the Default Trigger

With the application running, open any standard text input program (such as Notepad or TextEdit) and type:

:espanso

The keyword will immediately disappear and expand into:

Hi there!

Locating and Editing Configurations

Espanso splits its settings into two primary directories inside a parent configuration folder:

• match/: Defines what actions and snippets Espanso executes. Fresh setups include match/base.yml.
• config/: Defines how expansions behave, managing global options and application-specific overrides. Fresh setups include config/default.yml.

To find the configuration directory path on your system, run:

espanso path

Depending on the operating system, the path corresponds to:

• Windows: %APPDATA%\espanso (such as C:\Users\user\AppData\Roaming\espanso)
• Linux: $XDG_CONFIG_HOME/espanso (such as /home/user/.config/espanso)
• macOS: $HOME/Library/Application Support/espanso (or $HOME/.config/espanso if manually moved while the app is stopped)

To quickly open the files in your system’s default terminal editor, run:

espanso edit

Adding Custom Matches

To add your own expansions, open $CONFIG/match/base.yml in a text editor. Matches follow YAML formatting, meaning space-based indentation is mandatory.

A basic rule associates a single trigger with a replace string:

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

To create a multi-line email sign-off matching :br, append the rule under the matches: key:

matches:
  - trigger: ":espanso"
    replace: "Hi there!"
  - trigger: ":br"
    replace: "Best Regards,\nJon Snow"

When the file is saved, Espanso automatically detects the file modification and reloads the active configuration. Typing :br in any typing field will then output the defined greeting.

Installing Hub Packages

Rather than authoring every snippet manually, users can download ready-made packages from the Espanso Hub store. For example, to install the basic emoji expansion set, execute:

espanso install basic-emojis

If the system does not reload the new rules automatically, trigger a manual restart by running:

espanso restart

Editor Support

Match and configuration files can be modified in any plain-text tool. Users may work with dedicated utilities such as EspansoEdit, or use full code editors like VSCode, VSCodium, or Neovim. When using modern editors, users can configure YAML language server schemas to validate syntax and highlight formatting mistakes in real time.

Pricing and requirements

Pricing and plans are subject to the official page. Espanso is distributed as a free, open-source project under the GNU General Public License version 3.0 (GPL-3.0). The project does not charge for its core software, though users who wish to support continued development can make voluntary donations via PayPal.

In terms of system requirements, Espanso runs across major desktop operating systems:

• Windows: Supported with code signing for binaries provided by SignPath.io through the SignPath Foundation.
• macOS: Supported natively across standard application environments.
• Linux: Supported on traditional desktop systems as well as experimental environments running Wayland.

The Linux implementation relies on underlying tools including libxdo and xclip, while Wayland support utilizes libxkbcommon and wl-clipboard. Across platforms, graphical user interface components rely on the wxWidgets library.

Who it is for

Espanso is designed for anyone looking to eliminate repetitive typing and automate boilerplate text generation:

• Everyday Typists and Communicators: Professionals who send regular email responses, support messages, or standard greetings can save time with custom shortcodes.
• Developers and System Administrators: Technical users can maintain system-wide programming snippets, invoke terminal commands, run custom automation scripts, and integrate dynamic outputs directly into their workflow.
• Privacy-Conscious Individuals: Because Espanso runs entirely locally without internet telemetry or keystroke logging, it fits users who require local-only text expansion.
• Cross-Platform Users: People who switch between Windows, macOS, and Linux can maintain an identical workflow and portable YAML configurations across all their computers.
• Writers and Power Users: Those who want an individualized autocorrect setup, rapid emoji insertion, or structured interactive text forms across every desktop app.

Alternatives

Another utility available for automating desktop actions and text expansion is AutoHotkey.

Users seeking a standalone open-source text expansion tool can also look into Beeftext.

Sources

• https://github.com/espanso/espanso
• https://espanso.org/docs/
• https://github.com/AutoHotkey/AutoHotkey
• https://github.com/xmichelo/Beeftext