Install on Linux

Find the right version

To use Espanso on Linux, you first need to determine whether your system is running a X11 or Wayland desktop environment. If you are unsure, please open a terminal and run the following command:

echo $XDG_SESSION_TYPE

If the above command doesn't output anything, please try with this method.

Now that you know your desktop environment, you're ready to choose the right method in the following section.

Choosing the right install method

There are multiple installation methods on Linux. This table summarizes them based on distribution and desktop environment:

Distribution	X11	Wayland
Ubuntu/Debian	DEB package (recommended), AppImage, Manual compilation	DEB package (recommended), Manual compilation
Fedora	AppImage (recommended), Manual compilation	Manual compilation
Arch/Manjaro	AppImage (recommended), Manual compilation	Manual compilation
Other distros	AppImage (recommended), Manual compilation	Manual compilation

We are continously improving the installation process, so expect more user-friendly methods soon.

Install on X11

Installing with DEB package (Ubuntu/Debian)

Espanso ships with a .deb package, making the installation convenient on Debian-based systems.

Start by downloading the package by running the following command inside a terminal:

wget https://github.com/espanso/espanso/releases/download/v2.2.1/espanso-debian-x11-amd64.deb

Verifying package checksum

If you want to verify the correctness of the archive, in the Github Releases page you will find the SHA256 hash in the file espanso-debian-x11-amd64-sha256.txt

You can now install the package using:

sudo apt install ./espanso-debian-x11-amd64.deb

From now on, you should have the espanso command available in the terminal (you can verify by running espanso --version).

At this point, you are ready to use espanso by registering it first as a Systemd service and then starting it with:

# Register espanso as a systemd service (required only once)
espanso service register

# Start espanso
espanso start

If you don't want to use espanso as a Systemd service, you can also start it in unmanaged mode with espanso start --unmanaged. Keep in mind that Espanso will not start automatically when running in unmanaged mode, so you will need to do so manually.

You are now ready to read the Getting Started tutorial!

Installing with AppImage (all distros)

To install the Espanso's AppImage, open a terminal and follow these steps:

# Create the $HOME/opt destination folder
mkdir -p ~/opt
# Download the AppImage inside it
wget -O ~/opt/Espanso.AppImage 'https://github.com/espanso/espanso/releases/download/v2.2.1/Espanso-X11.AppImage'
# Make it executable
chmod u+x ~/opt/Espanso.AppImage
# Create the "espanso" command alias
sudo ~/opt/Espanso.AppImage env-path register

From now on, you should have the espanso command available in the terminal (you can verify by running espanso --version).

At this point, you are ready to use espanso by registering it first as a Systemd service and then starting it with:

# Register espanso as a systemd service (required only once)
espanso service register

# Start espanso
espanso start

If you don't want to use espanso as a Systemd service, you can also start it in unmanaged mode with espanso start --unmanaged. Keep in mind that Espanso will not start automatically when running in unmanaged mode, so you will need to do so manually.

You are now ready to read the Getting Started tutorial!

Compiling from sources

Prerequisites

These are the basic tools required to build espanso:

• A recent Rust compiler. You can install it following these instructions: https://www.rust-lang.org/tools/install

• A C/C++ compiler. On Linux, you should use the default C/C++ compiler (it's usually GCC). If you run the command specified in the next step, this will be included automatically.

• Install the required linux packages:

  • On Ubuntu/Debian run sudo apt update && sudo apt install build-essential git libx11-dev libxtst-dev libxkbcommon-dev libdbus-1-dev ^libwxgtk3\.[0-9].*-dev$ libssl-dev

• Espanso heavily relies on cargo make for the various packaging steps. You can install it by running:

cargo install --force cargo-make --version 0.34.0

Compiling Espanso

Once you've got all the prerequisites, you can:

# Clone the Espanso repository
git clone https://github.com/espanso/espanso

cd espanso

# Compile espanso in release mode
# NOTE: this will take a while (~5/15 minutes)
cargo make --profile release build-binary 

At this point, you should have the espanso binary available in the target/release/ directory.

Installing Espanso

Once you've compiled Espanso, you can move it into the final location. A good option would be the /usr/local/bin folder:

sudo mv target/release/espanso /usr/local/bin/espanso

From now on, you should have the espanso command available in the terminal (you can verify by running espanso --version).

At this point, you are ready to use espanso by registering it first as a Systemd service and then starting it with:

# Register espanso as a systemd service (required only once)
espanso service register

# Start espanso
espanso start

If you don't want to use espanso as a Systemd service, you can also start it in unmanaged mode with espanso start --unmanaged. Keep in mind that Espanso will not start automatically when running in unmanaged mode, so you will need to do so manually.

You are now ready to read the Getting Started tutorial!

Install on Wayland

Wayland support is currently experimental, therefore some features might be missing or not working well yet. Known limitations include:

• If you are using a non-us keyboard layout, you'll need to explicitly specify it in the settings (more on this below).
• There is currently no support for App-specific configurations, which means we can't use patches (which are often necessary to support some terminals).
• If you are using Gnome, Espanso causes a small "flicker" when using the clipboard backend. This does not happen on Sway.
• If you connect a new keyboard, you will need to manually restart Espanso with espanso restart, otherwise Espanso won't detect it.

If you encounter a bug, please open an issue on GitHub, any help is greatly appreciated! :)

Installing with DEB package (Ubuntu/Debian)

Espanso ships with a .deb package, making the installation convenient on Debian-based systems.

Start by downloading the package by running the following command inside a terminal:

wget https://github.com/espanso/espanso/releases/download/v2.2.1/espanso-debian-wayland-amd64.deb

Verifying package checksum

If you want to verify the correctness of the archive, in the Github Releases page you will find the SHA256 hash in the file espanso-debian-wayland-amd64-sha256.txt

You can now install the package using:

sudo apt install ./espanso-debian-wayland-amd64.deb

The process is almost complete, you just need to grant the required capabilities.

Adding the required Capabilities

Espanso requires access to the /dev/input/eventX and /dev/uinput interfaces to detect triggers and inject expansions respectively. Although you could run it as root to grant the necessary permissions, Espanso supports a safer alternative that consists in adding the CAP_DAC_OVERRIDE capability to the binary's set of Permitted ones. To do so, run the following command:

sudo setcap "cap_dac_override+p" $(which espanso)

Security considerations

In a nutshell, this capability grants Espanso the permissions to read and write to any file in the system, but only when explicitly activated by the binary itself.

To limit the attack surface, Espanso performs the following steps:

• When started, the CAP_DAC_OVERRIDE capability is contained in the Permitted set. At this point, Espanso CANNOT access arbitrary files in the system, as this is only possible once the CAP_DAC_OVERRIDE is moved to the Effective set.

• After a partial initialization of the various modules, Espanso moves the CAP_DAC_OVERRIDE permission to the Effective set and opens the necessary interfaces to the /dev/input/eventX and /dev/uinput files.

• Immediately after, the Permitted and Effective sets are cleared, meaning Espanso cannot access privileged files anymore. Moreover, because the Permitted set was cleared as well, the process won't be able to grant the permission again.

  In short, Espanso uses the CAP_DAC_OVERRIDE permission only when opening the /dev/input* interfaces, and ungrant that permission immediately after.

  For more information on Linux capabilities, see: https://man7.org/linux/man-pages/man7/capabilities.7.html

Final steps

Now run espanso --version. If you see the version appear, it means Espanso was successfully installed!

To complete the configuration, run these commands:

# Register espanso as a systemd service (required only once)
espanso service register

# Start espanso
espanso start

If you don't want to use espanso as a Systemd service, you can also start it in unmanaged mode with espanso start --unmanaged. Keep in mind that Espanso will not start automatically when running in unmanaged mode, so you will need to do so manually.

Keyboards

If you are using a non-US keyboard layout (and some US variants), you'll need to specify its "code" into the $CONFIG/config/default.yml file as follows:

# For example, this is what I use for the Italian layout
keyboard_layout:
  layout: "it"

The keyboard_layout: object accepts rules:, model:, layout:, variant: and options: fields.

Your current system settings may be displayed with one of the following commands: setxkbmap -query, localectl status, swaymsg -t get_inputs, gsettings get org.gnome.desktop.input-sources sources or echo $XKB_DEFAULT_LAYOUT, depending on your desktop environment.

You are now ready to read the Getting Started tutorial!

Compiling from sources

Prerequisites

These are the basic tools required to build espanso:

• A recent Rust compiler. You can install it following these instructions: https://www.rust-lang.org/tools/install

• A C/C++ compiler. On Linux, you should use the default C/C++ compiler (it's usually GCC). If you run the command specified in the next step, this will be included automatically.

• Install the required linux packages:

  • On Ubuntu/Debian run sudo apt update && sudo apt install build-essential git wl-clipboard libxkbcommon-dev libdbus-1-dev ^libwxgtk3\.[0-9].*-dev$ libssl-dev
  • On Fedora run sudo dnf install @development-tools gcc-c++ wl-clipboard libxkbcommon-devel dbus-devel wxGTK-devel.x86_64

• Espanso heavily relies on cargo make for the various packaging steps. You can install it by running:

cargo install --force cargo-make --version 0.34.0

Compiling Espanso

Once you've got all the prerequisites, you can:

# Clone the Espanso repository
git clone https://github.com/espanso/espanso

cd espanso

# Compile espanso in release mode
# NOTE: this will take a while (~5/15 minutes)
cargo make --profile release --env NO_X11=true build-binary 

At this point, you should have the espanso binary available in the target/release/ directory.

Installing Espanso

Once you've compiled Espanso, you can move it into the final location. A good option would be the /usr/local/bin folder:

sudo mv target/release/espanso /usr/local/bin/espanso

The process is almost complete, you just need to grant the required capabilities.

Adding the required Capabilities

Espanso requires access to the /dev/input/eventX and /dev/uinput interfaces to detect triggers and inject expansions respectively. Although you could run it as root to grant the necessary permissions, Espanso supports a safer alternative that consists in adding the CAP_DAC_OVERRIDE capability to the binary's set of Permitted ones. To do so, run the following command:

sudo setcap "cap_dac_override+p" $(which espanso)

Security considerations

In a nutshell, this capability grants Espanso the permissions to read and write to any file in the system, but only when explicitly activated by the binary itself.

To limit the attack surface, Espanso performs the following steps:

• When started, the CAP_DAC_OVERRIDE capability is contained in the Permitted set. At this point, Espanso CANNOT access arbitrary files in the system, as this is only possible once the CAP_DAC_OVERRIDE is moved to the Effective set.

• After a partial initialization of the various modules, Espanso moves the CAP_DAC_OVERRIDE permission to the Effective set and opens the necessary interfaces to the /dev/input/eventX and /dev/uinput files.

• Immediately after, the Permitted and Effective sets are cleared, meaning Espanso cannot access privileged files anymore. Moreover, because the Permitted set was cleared as well, the process won't be able to grant the permission again.

  In short, Espanso uses the CAP_DAC_OVERRIDE permission only when opening the /dev/input* interfaces, and ungrant that permission immediately after.

  For more information on Linux capabilities, see: https://man7.org/linux/man-pages/man7/capabilities.7.html

Final steps

Now run espanso --version. If you see the version appear, it means Espanso was successfully installed!

To complete the configuration, run these commands:

# Register espanso as a systemd service (required only once)
espanso service register

# Start espanso
espanso start

If you don't want to use espanso as a Systemd service, you can also start it in unmanaged mode with espanso start --unmanaged. Keep in mind that Espanso will not start automatically when running in unmanaged mode, so you will need to do so manually.

Keyboards

If you are using a non-US keyboard layout (and some US variants), you'll need to specify its "code" into the $CONFIG/config/default.yml file as follows:

# For example, this is what I use for the Italian layout
keyboard_layout:
  layout: "it"

The keyboard_layout: object accepts rules:, model:, layout:, variant: and options: fields.

Your current system settings may be displayed with one of the following commands: setxkbmap -query, localectl status, swaymsg -t get_inputs, gsettings get org.gnome.desktop.input-sources sources or echo $XKB_DEFAULT_LAYOUT, depending on your desktop environment.

You are now ready to read the Getting Started tutorial!