Skip to content

linux.mdx

Latest commit

 

History

History
211 lines (138 loc) · 7.38 KB

linux.mdx

File metadata and controls

211 lines (138 loc) · 7.38 KB
title layout
Install on Linux
docs

import siteConfig from '/docusaurus.config.js'; import {getStableDownloadLink} from '/src/utils/versionUtils.js'; import CodeBlock from '@theme/CodeBlock'; import X11AfterInstall from "./linux/_x11-after-install.mdx"; import WaylandFinalSteps from "./linux/_wayland-final-steps.mdx";

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) {#deb-x11}

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:

export const DebX11CodeLink = () => wget {getStableDownloadLink("LINUX_X11_DEB_DOWNLOAD_URL")};

:::info 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 dpkg -i ./espanso-debian-x11-amd64.deb

Installing with AppImage (all distros) {#appimage-x11}

export const AppImageCodeLink= () => {`# Create the $HOME/opt destination folder mkdir -p ~/opt

Download the AppImage inside it

wget -O ~/opt/Espanso.AppImage '${getStableDownloadLink("LINUX_X11_APP_IMAGE_DOWNLOAD_URL")}'

Make it executable

chmod u+x ~/opt/Espanso.AppImage

Create the "espanso" command alias

sudo ~/opt/Espanso.AppImage env-path register `};

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

Compiling from sources {#x11-compile}

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 libssl-dev libwxgtk3.*-dev

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 build -p espanso --release --no-default-features --features vendored-tls,modulo

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

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) {#deb-wayland}

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:

export const DebWaylandCodeLink = () => wget {getStableDownloadLink("LINUX_WAYLAND_DEB_DOWNLOAD_URL")};

:::info 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.

Compiling from sources {#wayland-compile}

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 libssl-dev libwxgtk3.*-dev
    • On Fedora run sudo dnf install @development-tools gcc-c++ wl-clipboard libxkbcommon-devel dbus-devel wxGTK-devel.x86_64

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 build -p espanso --release --no-default-features --features modulo,vendored-tls,wayland

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.