Skip to content

Quick start

  • Linux with systemd (Arch, Debian, Ubuntu, Fedora, openSUSE, etc.)
  • Python 3.11-3.15
  • Wayland or X11 session (GNOME, KDE Plasma, Sway, Hyprland, Niri, etc.).
  • Clipboard/window tools:
    • wl-clipboard and wtype on Wayland
    • python-pyperclip, xclip, xdotool, and xprop on X11 (installed by the dependency script)
  • Waybar or Noctalia (optional, for status bar)
  • gtk4 + PyCairo (optional, for visualizer)
  • NVIDIA GPU (optional, for CUDA acceleration)
  • AMD/Intel GPU / APU (optional, for Vulkan acceleration)

Use the Nix flake and NixOS module for a packaged Whisper.cpp CPU runtime. Nix installations use configuration and model commands instead of the interactive installer. We’d appreciate issue reports.

On the AUR:

Terminal window
# Install for stable
yay -S hyprwhspr
# Or install for bleeding edge
yay -S hyprwhspr-git

Then run the interactive setup:

Terminal window
hyprwhspr setup
Terminal window
curl -fsSL https://hyprwhspr.com/install.sh | bash

Installs dependencies and the latest release, then walks you through setup.

Manual install
Terminal window
# Clone the repo
git clone https://github.com/goodroot/hyprwhspr.git
cd hyprwhspr
# Install dependencies for your distro
./scripts/install-deps.sh
# Run interactive setup
./bin/hyprwhspr setup

Setup: pick a backend, review your preferences and choose desktop integrations. Setup asks before changing your bar or desktop shortcuts. Backend and model downloads can take several minutes. Follow the final checks and any remaining steps before trying dictation.

Want to choose everything? Answer no to recommended settings.

For automatic backend selection and default settings:

Terminal window
hyprwhspr setup auto

Authentication may still ask for your password.

Ensure your microphone of choice is available in audio settings!

  1. Log out and back in if setup asked you to
  2. Press Super+Alt+D to start dictation - beep!
  3. Speak naturally
  4. Press Super+Alt+D again to stop dictation - boop!
  5. Bam! Text appears in active buffer!

Recording indicator: when enabled and its dependencies are available, supported desktops show an overlay or a status notification. Noctalia / Omarchy can match the overlay to your shell theme. See Themed visualizer for details.

Any snags, please create an issue.

Terminal window
# Arch: update via your AUR helper
yay -Syu hyprwhspr
# Installed with install.sh
hyprwhspr update
# Old git-clone installs: re-run the installer once to move to releases
curl -fsSL https://hyprwhspr.com/install.sh | bash
# Either way, setup is idempotent if you need to re-run it
hyprwhspr setup

Managed release rollout and recovery: installation guide.