Skip to main content
Version: 2.0.0-alpha ๐Ÿšง

What changed in v2

Although the v2 strives to be backward compatible, the configuration format has slightly changed. Luckily, Espanso comes with an automatic migration tool that makes the switch almost painless.

Before diving into the tool though, we are going to explore the main changes.

New configuration format#

Previously, configurations and matches were defined in the same file (usually the default.yml file). In v2, the two have been split:

  • You should now define your matches and global variables in the $CONFIG/match/base.yml file.
  • Other configuration options (like toggle_key or backend) should be defined in the $CONFIG/config/default.yml file.

For example, this legacy config file:

backend: Clipboard
matches:  - trigger: ":espanso"    replace: "Hi there!"

would be divided in two separate files:

matches:  - trigger: ":espanso"    replace: "Hi there!"
backend: Clipboard

Espanso comes with an automatic migration tool, simply launch it and the wizard will ask you to migrate the configurations automatically.

For a deeper walkthrough on the new configuration format, please read the Configuration changes section.

Search bar#

Espanso now comes with a search bar. You can open it typing jkj or by pressing ALT+SPACE (or OPTION+SPACE on macOS). You can customize the shortcut with these options (you should add them into the default.yml file):

search_trigger: "jkj"search_shortcut: "ALT+SPACE"

Regex triggers#

You can now write full-blown regex triggers with named groups:

  - regex: ":hi\\((?P<name>.*?)\\)"    replace: "Hey {{name}}!"

The named group name is injected as a variable.

Only use Regex triggers when necessary, as their performance is significantly slower than regular triggers.

Currently there is a limit of 30-chars in the regex trigger (including the argument) due to performance reasons. We are working to make this limit configurable, but we are not yet there.

Distribution format#

Espanso v2 slightly changes the preferred distribution format on some platforms.


Espanso is now a regular App Bundle on macOS, currently available for both Intel and M1 architectures.


Espanso now ships as an AppImage by default for X11 systems. We are still deciding the optimal distribution format for Wayland systems.


You can now use the official installer or the Portable mode to use Espanso on Windows.

New Package system#

Espanso v2 ships with a new and improved package system. We are still working out the last details, so currently is not possible to install a package from the Espanso Hub, but we are working to make this available as soon as possible.

Among the new features, you can now:

  • Install a package from private git repositories
  • Install a package from GitLab repositories

Experimental Wayland support#

Espanso v2 ships with experimental Wayland support. There are still some rough edges to be solved before considering the experience stable, but it should be quite usable already.

Please report any bug that you experience on GitHub! :)

Other changes#

  • The GUI layer modulo is now built-in into Espanso, and does not require a separate binary.
  • Espanso now uses native notifications on Windows.

Espanso v2 ships with many other changes that were not documented in this section yet. We are in the process of rewriting the docs, so please be patient :)


Hi! I'm Federico, the creator of espanso. I develop espanso in my (little) spare time and I decided to make it open source because I thought it could be useful to many people.

If you liked the project, please consider making a small donation, it really helps :)

A special thanks goes to all the wonderful people who supported espanso along the way

Together, we will make espanso the first universal text expander, open to everyone.


Espanso is open source and hosted on GitHub.


If you find a bug or have an idea for a new feature, please open an issue on GitHub.