Skip to main content
Version: v0.7.3 (Legacy)


Following a Unix-like philosophy, espanso uses files to manage its configuration instead of GUIs. This has many advantages, such as the capability to easily sync your configurations between machines using Git or cloud services such as Dropbox or Google Drive.


All espanso configurations reside in a folder called espanso, whose location varies between Operating Systems:

  • Linux: $XDG_CONFIG_HOME/espanso (e.g. /home/user/.config/espanso)
  • macOS: $HOME/Library/Preferences/espanso (e.g. /Users/user/Library/Preferences/espanso)
  • Windows: {FOLDERID_RoamingAppData}\espanso (e.g. C:\Users\user\AppData\Roaming\espanso)

A quick way to find the path of your configuration folder is by using the following command:

espanso path

The espanso directory will contain the following file structure:

- default.yml
- user/

The default.yml file contains the main configurations and for a basic usage, this is the only file you will be working with. You can find a list of all the possible options in the Options section.

The user folder is used to store more advanced user configurations, such as Application-specific configs.

Quick Editing

Introduced in version 0.5.1, espanso now ships with the edit subcommand, which makes editing configuration files much more convenient. Let's see how it works:

If you open a terminal and type:

espanso edit

the default system editor (Notepad on Windows and Nano on Unix systems) will be spawned, editing the default.yml. Then, after you saved the file and exited the editor, espanso will automatically restart, loading the new changes.

Customizing the editor

If you want to use another editor, customizing it is super easy, just specify your choice in the EDITOR (or VISUAL) environment variables, such as:


Editing files in the user/ directory

If you invoke espanso edit without further arguments, it will open the default.yml file. But what if you want to edit files in the user/* directory? Luckily, you can simply specify the name as an additional argument (without the extension).

For example, if you want to edit the user/emails.yml file, you can type:

espanso edit emails

Note that the last command also allows the user to create a new file in the user/ directory if it doesn't already exist.

Organizing Matches

After creating a lot of matches, you may wonder if there's a way to keep them organized in multiple files instead of creating a long list in the default.yml configuration. Luckily, you can split your matches into multiple files by placing them in the user/ folder!

Let's say you want to create a file for your email signatures. Create the user/emails.yml file with the following content:

name: emails
parent: default

- trigger: ":sig"
replace: |
Best regards,
Jon Snow

After restarting espanso (by using the espanso restart command), you can now use the :sig trigger as you would have done by inserting it into the default.yml configuration.

This is made possible by the parent: default instruction, which tells espanso to merge the current matches into the default configuration.

You can create as many files as you want, and keep all your matches well organized :)

Application-Specific Configurations

Sometimes you may need to make espanso behave differently with some applications. For example, you may want to have a different set of Matches for an application, or you may need to change the backend option for compatibility purposes.

For such cases, espanso offers the Application Specific configurations, that is configurations that are valid only for some applications which match specific filters.

Let's say you want to add some Matches for emojis, but only when using the Telegram desktop app.

You can create a telegram.yml file in the espanso/user folder, with the following content:

filter_title: "Telegram"

- trigger: ":ok"
replace: "👍"

After restarting espanso with espanso restart, you are ready to test the new configuration.

Navigate to Telegram and type :ok, you should see your emoji appear. If you then move to another application and try again, you should not see it!

The key here is the filter_title option, that basically means: "If the current application contains Telegram in the title, use this configuration instead of the default.yml one"

Note: app-specific configurations don't support all options, refer to the table below to find out more.

Available Filters

espanso supports various filters, but their support depends on the Operating System used. You can refer to this table:

FilterDescriptionWindows SupportMacOS SupportLinux Support
filter_titleFilter based on the current Window titleFull supportUses the App identifier instead of the Window titleFull support
filter_execFilter based on the current application executable pathFull supportFull supportPartial support
filter_classFilter based on the current Window classUses the application executable path insteadUses the App identifier insteadFull support

The filter_title, filter_exec and filter_class filters support a full regex as parameter, but make sure to escape the special characters properly.

Finding the right filters

To make it easier to find the right filters, espanso offers the detect subcommand. Open a terminal and type:

espanso detect

Now, while leaving it running, move to the desired application and then come back to the terminal. You should see an output like:

Detected change, current window has properties:
==> Title: 'Telegram (1828)'
==> Class: 'TelegramDesktop'
==> Executable: '/snap/telegram-desktop/953/bin/Telegram'

These are the parameters espanso detected for your target application, so you can now use them to create the perfect filter.

Customizing the Toggle Key

By default, espanso can be temporarily disabled and enabled by pressing the Alt key twice, resulting in a notification saying "espanso disabled." Pressing Alt twice again will enable it, and you'll receive a notification saying "espanso enabled."

If you'd like to customize the key, simply add the toggle_key option to your default.yml configuration and set it to one of the available options:


And if you'd rather turn it off, you can do so with:

toggle_key: OFF

Hiding the Icon

You can hide the espanso icon on macOS and Windows by adding the following option to your default.yml file:

show_icon: false

Hiding the Notifications

You can hide the espanso notifications by adding the following option to your default.yml config:

show_notifications: false

Note for macOS users: if you only want to hide the SecureInput notifications, please read the following section.1

macOS Notification for SecureInput

On macOS there is a security feature known as SecureInput, which blocks text expanders from detecting input when entering text in sensitive areas, such as password fields (but also other apps, even the Terminal if configured).

As a result, espanso will not work in those situations, and espanso will trigger a notification (as well as logging it) to warn the user if an app triggers SecureInput. If you want to disable the notification, just add the following line in your config file:

secure_input_notification: false


Here's a list of all options available for the configuration file:

OptionDescriptionPossible ValuesDefaultApp-Specific
backendThe typing engine used. Inject simulate keypresses, Clipboard simulates a copy/paste, Auto is available on Linux only and combines the two previous.Clipboard, Inject or Auto (Linux only)Inject on Win and macOS, Auto on LinuxYes
auto_restartRestart when the configuration changestrue/falsetrueNo
backspace_limitHow many backspace espanso tracks to correct misspelled keywordsint3No
enable_activeDisable the active mode for the current configurationtrue/falsetrueYes
enable_passiveDisable the passive mode for the current configurationtrue/falsefalseYes
parentThe target for the current configuration file, mainly used in packagesstringselfYes
ipc_server_portWindows only. Set the daemon listening portint34982No
exclude_default_entriesUsed in app-specific configs, avoid parent matches and global variablestrue/falsefalseYes
secure_input_notificationEnable/Disable the Secure Input notification on macOStrue/falsetrueNo
show_iconShow/Hide the icon in the status bar on macOS and Windowstrue/falsetrueNo
show_notificationsShow/Hide the notificationstrue/falsetrueNo
undo_backspaceEnable/Disable the Backspace-To-Undo featuretrue/falsetrueYes
fast_injectUse a faster injection mechanism (Linux only). It uses XSendEvent API rather than XTestFakeKeyEvent API, which is faster but incompatible with some applications.true/falsetrueYes


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.