---
title: Configuration
layout: docs
---
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](https://git-scm.com/) or cloud services
such as [Dropbox](https://www.dropbox.com/) or [Google Drive](https://www.google.com/drive/).

### Structure

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](#options) section. 

The `user` folder is used to store more advanced user configurations, such as [Application-specific](#application-specific-configurations) configs.

#### Migrating from versions prior to v0.3.0

Prior to version v0.3.0, espanso located all configurations in the user home directory, into the `.espanso` folder.
This location is now deprecated and, while being still supported for compatibility purposes, you should migrate to the new one with the following steps:

* Copy the `default.yml` and the `user/` directory in the new `espanso` config folder ( you can find the new config location with the `espanso path` command ).
* Copy the contents of the `packages` folder into the new `packages` path ( you can find the new package 
location with the `espanso path` command ).

### 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`)
envorionment variables, such as:

```
EDITOR=/usr/bin/vim
```

#### 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:

```yml
name: emails
parent: default

matches:
  - 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:

```yml
filter_title: "Telegram"

matches:
  - 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](#options) 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:

Filter | Description | Windows Support | MacOS Support | Linux Support
--- | --- | --- | --- | ---
`filter_title` | Filter based on the current Window title | Full support | Uses the App identifier instead of the Window title | Full support
`filter_exec` | Filter based on the current application executable path | Full support | Full support | Partial support
`filter_class` | Filter based on the current Window class | Uses the application executable path instead | Uses the App identifier instead | Full support

The `filter_title`, `filter_exec` and `filter_class` filters support a full **regex** as parameter.

#### 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.

### Options

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

Option | Description | Possible Values | Default | App-Specific 
--- | --- | --- | --- | ---
`backend` | The 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 Linux | Yes
`backspace_limit` | How many backspace espanso tracks to correct misspelled keywords | int | `3` | No
`enable_active` | Disable the active mode for the current configuration | `true`/`false` | `true` | Yes
`enable_passive` | Disable the passive mode for the current configuration | `true`/`false` | `false` | Yes
`parent` | The target for the current configuration file, mainly used in packages | string | `self` | Yes
`ipc_server_port` | Windows only. Set the daemon listening port | int | `34982` | No
`exclude_default_entries` | Used in app-specific configs, avoid parent matches and global variables | `true`/`false` | `false` | Yes
`toggle_key` | Change the key used to toggle espanso active mode | `CTRL`, `ALT`, `SHIFT`, `META`, `LEFT_CTRL`, `LEFT_ALT`, `LEFT_SHIFT`, `LEFT_META`, `RIGHT_CTRL`, `RIGHT_ALT`, `RIGHT_SHIFT`, `RIGHT_META`, `OFF`| `ALT` | No
`passive_key` | Change the key used to trigger passive mode | `CTRL`, `ALT`, `SHIFT`, `META`, `LEFT_CTRL`, `LEFT_ALT`, `LEFT_SHIFT`, `LEFT_META`, `RIGHT_CTRL`, `RIGHT_ALT`, `RIGHT_SHIFT`, `RIGHT_META`, `OFF`| `OFF` | No
`secure_input_notification` | Enable/Disable the Secure Input notification on macOS | `true`/`false` | `true` | No
`show_icon` | Show/Hide the icon in the status bar on macOS and Windows | `true`/`false` | `true` | No
`show_notifications` | Show/Hide the notifications| `true`/`false` | `true` | No