Installing HyperVoice on Linux (beta)

Step 1 — Download

Grab the AppImage from your dashboard, or directly from hypervoice.app/api/download/linux. It's a single ~100 MB file — your browser will save it to ~/Downloads/ by default.

Step 2 — Make it executable

AppImages aren't executable by default after download. Two ways to fix that:

From a terminal:

chmod +x ~/Downloads/HyperVoice_*_amd64.AppImage

From your file manager: right-click the file → Properties → Permissions tab → check "Allow executing file as program". (Exact wording varies: Nautilus / GNOME Files, Dolphin / KDE, Thunar / XFCE all have an equivalent toggle.)

GNOME Files 44+ doesn't show "Allow executing"?

Recent GNOME (Ubuntu 23.10+, Fedora 38+) deliberately removed the permission toggle for security reasons. Use the terminal command above instead. The AppImage will then double-click-launch from Files normally.

Step 3 — Run it

Either double-click the file in your file manager, or run it directly:

~/Downloads/HyperVoice_0.6.7_amd64.AppImage

First launch downloads a Whisper speech model (default Tiny English ~75 MB) and walks you through hotkey setup. After that, press your hotkey anywhere on your desktop and dictate — same as the Windows build.

Tip — move it to ~/Applications/ for tidiness

Most GNOME / KDE / Cinnamon launchers auto-detect AppImages in ~/Applications/ and add them to your apps menu so you can launch from the Activities overview just like a regular app. Optional, but nice.

"AppImage won't open" / FUSE missing

AppImages mount themselves at runtime via FUSE. Most desktop Linuxes ship with it, but a few don't out of the box — most notably Ubuntu 24.04, which dropped the legacy libfuse2 package and uses libfuse2t64 instead. If your AppImage double-click does nothing, or you see an error mentioning libfuse / fusermount, install it:

Ubuntu 24.04+ / Debian 13+:
```
sudo apt install libfuse2t64
```
Ubuntu 22.04 / Debian 12:
```
sudo apt install libfuse2
```
Fedora 35+:
```
sudo dnf install fuse fuse-libs
```
Arch / Manjaro:
```
sudo pacman -S fuse2
```

Wayland session — switch to X11 first

HyperVoice currently requires an X11 session. Wayland users see the app launch and the UI render, but the global hotkey won't register and paste won't reach the target window — Wayland blocks the cross-app focus/input APIs we depend on. The portal-based replacements aren't ready yet (we're tracking it).

Most major distros let you switch session at login:

Ubuntu (GNOME) — at the login screen, click your username, then the gear icon in the bottom-right → pick "Ubuntu on Xorg".
Fedora (GNOME) — same as Ubuntu: gear icon at the login screen → "GNOME on Xorg".
KDE Plasma — login screen → session menu (gear or session-name button) → pick "Plasma (X11)".
Pop!_OS — install the X11 session: sudo apt install gnome-session-xorg, then logout and pick it from the login session menu.

Wayland support is on the roadmap once xdg-desktop-portal exposes the focus-restore / global-shortcuts APIs HyperVoice needs.

"It signs me in but forgets next launch"

HyperVoice stores your session token in the Secret Service (the standard Linux keyring API). If no keyring daemon is running, sign-in works once but doesn't persist across restarts. Most desktop environments include one by default:

GNOME / Ubuntu / Pop!_OS: gnome-keyring ships pre-installed and starts with your session.
KDE: kwalletmanager5 / kwalletmanager6 provides the Secret Service.
Minimalist setups (i3, sway, bspwm with no DE): install gnome-keyring or keepassxc (with Secret Service enabled in Settings → Browser Integration), then start it as part of your session.

On Debian/Ubuntu: sudo apt install gnome-keyring and re-login.

Linux known limitations (beta)

X11 session required. See above. Wayland support is blocked on upstream portal work.
Whisper engine only. The optional Parakeet engine (Settings → Dictation) is Windows-only because the underlying DirectML execution provider is a Windows API. Whisper handles all the same languages and runs on Vulkan GPU.
Beta-quality. The Linux build hasn't seen as much real-world testing as the Windows build. Hitting a bug? Email support@hypervoice.app or report it in HyperVoice Community — most issues get patched within a day or two.

Updating HyperVoice

HyperVoice has a built-in auto-updater — when a new version ships, you'll see a banner inside the app with a "Download & restart" button. The updater swaps the AppImage in place and relaunches.

If you'd rather check manually, the dashboard always serves the latest AppImage from hypervoice.app/api/download/linux — replace your existing file and you're done.

Still stuck?

Two fast paths to get unblocked:

Ask in Discord — join the HyperVoice Community and drop a message in #install-help. Linux questions answered fast — usually by users who've solved the same thing.
Email us — support@hypervoice.app. Include your distro + version (lsb_release -d) and any error message from running the AppImage in a terminal.