Vocalinux
982

Debian Setup Guide

Install Voice Dictation on Debian

Debian 12 and newer are a primary target for Vocalinux. The install script detects Debian, installs the system packages it needs, and sets up whisper.cpp with a checksum-verified tiny model.

Install command

curl -fsSL https://raw.githubusercontent.com/VocaHQ/vocalinux/main/install.sh -o /tmp/vl.sh bash /tmp/vl.sh

Prerequisites

  • Debian 12 or newer, including Testing (Debian 11 and earlier are below the Python 3.11 floor)
  • Python 3.11+ with the distro's python3-gi (the installer handles this)
  • Working microphone
  • curl installed (sudo apt update && sudo apt install -y curl)

Supported on

  • Debian 12 and newer: full support
  • Debian Testing: full support

Support levels come from the project’s distribution compatibility matrix. They describe expected compatibility, not a list of test machines.

Other install options for Debian

Native .deb package

Download the .deb for your CPU from GitHub Releases (arm64 files are attached too). It is a thin package: Python and GTK come from the distro, whisper.cpp runs on the CPU, and there is no auto-update. On Wayland, add yourself to the input group (sudo usermod -aG input $USER, then log out and back in) or the default hotkey stays off.

sudo apt install ./vocalinux_*_amd64.deb

Flatpak from the VocaHQ remote

Not on Flathub. The self-hosted vocahq remote updates with flatpak update and ships whisper.cpp only.

flatpak install https://vocahq.github.io/vocalinux-flatpak/com.vocalinux.Vocalinux.flatpakref

Compare every package format on theinstall overview, or read theFlatpak guide.

Setup notes for Debian

  1. Debian uses the Ayatana AppIndicator for the tray (gir1.2-ayatanaappindicator3-0.1); the installer picks it.
  2. Clean Debian installs lack some build tools for compiling pywhispercpp (libssl-dev, autoconf, automake, libtool, patchelf). The installer adds them; add them yourself before a manual rebuild.
  3. ydotool is not in Debian's standard repositories. Vocalinux falls back to IBus or wtype for most Wayland compositors.
  4. On KDE Plasma Wayland, set System Settings → Keyboard → Virtual Keyboard to IBus Wayland.

Post-install checklist

  • Run vocalinux --version to confirm the installed release.
  • Launch vocalinux and confirm the tray icon appears. On GNOME, the tray needs the AppIndicator extension.
  • Hold Right Alt (Option) to dictate, or switch to toggle mode in Settings → Shortcuts, and confirm text lands in a terminal and a browser.
  • If anything misbehaves, run vocalinux --debug and check the troubleshooting guide.
  • On GNOME, install gnome-shell-extension-appindicator if the tray icon never appears.

Need help selecting an engine? Read theengine comparison. Stuck? Seetroubleshooting.