Installation¶

Requirements¶

Linux with GNOME Shell 47+ on Wayland
Working microphone
~2 GB disk space for models
Python 3.10–3.14 — source install only; the prebuilt packages bundle their own runtime

Tested on Fedora and NixOS.

Quick install (prebuilt packages)¶

The easiest path. Download the latest app package and a language pack from the Releases page and install them together — just take the latest of each; the app and language-pack version numbers are independent and need not match:

Debian / UbuntuFedora / RHEL

sudo apt install ./easyspeak_*_amd64.deb ./easyspeak-lang-en_*_all.deb

sudo dnf install ./easyspeak-*.x86_64.rpm ./easyspeak-lang-en-*.noarch.rpm

This bundles the Python runtime, Piper, the GNOME Shell extension, and the speech models — no pip/uv step and no compiler. Log out and back in once after the first launch so GNOME loads the bundled extension. See the Packaging guide for offline notes, more languages, and hold-to-dictate setup.

NixOS¶

The flake carries the runtime tools, the Piper voice and the sound theme, so there is no system-package step:

nix run github:ctsdownloads/easyspeak

Log out and back in once after the first launch so GNOME loads the bundled Shell extension. See Contributing for the dev shell.

Install from source¶

For development, or to run the latest unreleased code, install from the repository. This path needs system build dependencies and a supported Python.

Python¶

EasySpeak is tested against Python 3.10, 3.11, 3.12, 3.13, and 3.14. Fedora 43's default python3 (3.14) works out of the box.

1. System packages¶

sudo dnf install \
  pipewire-utils \
  wireplumber \
  at-spi2-core \
  python3-gobject \
  libadwaita \
  qutebrowser \
  glib2 \
  ffmpeg-free \
  pulseaudio-utils \
  sound-theme-freedesktop \
  wl-clipboard \
  portaudio-devel \
  python3-devel \
  gcc

wl-clipboard is what dictation uses to place text. It types by putting the text on the clipboard and sending a paste keystroke, because accessibility-level insertion is silently ignored by Chromium-based applications — they accept the call, report success, and discard the text. Without wl-clipboard, dictation falls back to that path and quietly does nothing in a browser.

python3-gobject and libadwaita power the tray menu's About EasySpeak window. They ship with any GNOME desktop, so they're usually already present; they're listed here for the sake of minimal or non-GNOME installs.

Optionally, sudo dnf install python3-adblock gives qutebrowser Brave's element-level ad blocker. EasySpeak configures the browser to use it when it is present and falls back to host blocking when it is not, so this is worth having: ad overlays are numbered like any other element, so they take link hints away from the page underneath.

2. Piper TTS¶

mkdir -p ~/.local/bin
cd ~/.local/bin
wget https://github.com/rhasspy/piper/releases/download/2023.11.14-2/piper_linux_x86_64.tar.gz
tar xzf piper_linux_x86_64.tar.gz
rm piper_linux_x86_64.tar.gz

echo 'export PATH="$HOME/.local/bin/piper:$PATH"' >> ~/.bashrc
source ~/.bashrc

mkdir -p ~/.local/share/piper
cd ~/.local/share/piper
wget -O en_US-amy-medium.onnx \
  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/amy/medium/en_US-amy-medium.onnx"
wget -O en_US-amy-medium.onnx.json \
  "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/amy/medium/en_US-amy-medium.onnx.json"

3. Clone the repository¶

git clone https://github.com/ctsdownloads/easyspeak.git ~/easyspeak
cd ~/easyspeak

4. Python packages¶

The simplest path is uv. Run it from the cloned repository and it does everything in one step — it creates and updates the virtual environment, installs every dependency declared in pyproject.toml, and launches EasySpeak from inside that environment. There's no separate "install the requirements" command; the first uv run sets it all up for you:

cd ~/easyspeak
uv run easyspeak

Prefer plain pip? Create a virtual environment first — most distributions ship their system Python as externally managed, so installing into it directly fails:

python3 -m venv ~/easyspeak-venv
source ~/easyspeak-venv/bin/activate
cd ~/easyspeak
pip install -e .
easyspeak

A Python-only installation has no bundled speech-recognition model, and EasySpeak stays offline by default (EASYSPEAK_OFFLINE=strict), so on first run it reports the model as missing. Set EASYSPEAK_OFFLINE=relaxed to have it fetch base.en (about 140 MB) from Hugging Face for you, or install a language pack.

Head tracking (optional)¶

Head tracking requires a webcam and additional dependencies. With uv, add the extra to the run command and it pulls them in for you:

uv run --extra head-tracking easyspeak

With a plain pip virtual environment, install the extra before running easyspeak:

pip install '.[head-tracking]'

The head-tracking extra pulls in sixdrepnet and opencv-python.