Linux Installation & Setup

System Requirements

OpenWhispr supports most modern Linux distributions with X11 or Wayland display servers.

Hardware Requirements

Processor: x64 (64-bit)
RAM: 4GB minimum (8GB recommended for local transcription)
Disk Space: 500MB for app + up to 3GB for local Whisper models

Tested Distributions

Ubuntu 20.04+ / Linux Mint / Pop!_OS
Debian 11+
Fedora 36+
Arch Linux / Manjaro
openSUSE Leap / Tumbleweed
GNOME, KDE Plasma, Sway, Hyprland desktop environments

Software Requirements

Node.js 18+ (for building from source)
GCC and development libraries (for compiling native binaries)

Installation Methods

OpenWhispr provides multiple package formats for maximum compatibility:

Download the .deb package

Download from GitHub Releases:

wget https://github.com/OpenWhispr/openwhispr/releases/download/v1.5.5/OpenWhispr-1.5.5-linux-x64.deb

Install with apt

sudo apt install ./OpenWhispr-1.5.5-linux-x64.deb

This automatically installs recommended dependencies:

ydotool (required for Wayland paste)
xdotool (suggested for X11 paste)
wtype (suggested for Wayland paste)
wl-clipboard (recommended for Wayland clipboard)

Launch OpenWhispr

open-whispr

Or find it in your application menu.

Download the .rpm package

wget https://github.com/OpenWhispr/openwhispr/releases/download/v1.5.5/OpenWhispr-1.5.5-linux-x64.rpm

Install with dnf

sudo dnf install ./OpenWhispr-1.5.5-linux-x64.rpm

Or with yum:

sudo yum install ./OpenWhispr-1.5.5-linux-x64.rpm

Install dependencies

sudo dnf install ydotool xdotool wtype wl-clipboard
sudo systemctl enable --now ydotoold

Download the AppImage

wget https://github.com/OpenWhispr/openwhispr/releases/download/v1.5.5/OpenWhispr-1.5.5-linux-x64.AppImage

Make it executable

chmod +x OpenWhispr-1.5.5-linux-x64.AppImage

Run the app

./OpenWhispr-1.5.5-linux-x64.AppImage

AppImage is portable and doesn’t require installation. Perfect for testing or running from USB drives.

Download and extract

wget https://github.com/OpenWhispr/openwhispr/releases/download/v1.5.5/OpenWhispr-1.5.5-linux-x64.tar.gz
tar -xzf OpenWhispr-1.5.5-linux-x64.tar.gz
cd OpenWhispr-1.5.5/

Run the app

./openwhispr

No root privileges required. Works on any distribution.

Install Flatpak runtime

flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user -y flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08

Install OpenWhispr

flatpak install --user ./OpenWhispr-1.5.5-linux-x64.flatpak

Run the app

flatpak run com.herotools.openwispr

Flatpak includes sandboxing with explicit permissions for microphone, clipboard, and file access.

Clone the repository

git clone https://github.com/OpenWhispr/openwhispr.git
cd openwhispr

Install build dependencies

Debian/Ubuntu:

sudo apt install gcc libx11-dev libxtst-dev

Fedora/RHEL:

sudo dnf install gcc libX11-devel libXtst-devel

Arch:

sudo pacman -S gcc libx11 libxtst

Install Node.js dependencies

npm install

Build the app

npm run build:linux

Output: dist/OpenWhispr-*-linux-x64.{AppImage,deb,rpm,tar.gz}

Clipboard Paste Tools

OpenWhispr requires at least one paste tool for automatic text insertion. The app tries methods in this order:

Native Binary (Primary Method)

OpenWhispr includes a native C binary (linux-fast-paste) that handles clipboard pasting on both X11 and Wayland.

How it works:

X11: Uses XTest extension to synthesize Ctrl+V keystrokes directly
Wayland (uinput): Creates a virtual keyboard via Linux uinput subsystem
Wayland (portal): Uses RemoteDesktop D-Bus portal on GNOME/KDE for native window targeting
Terminal detection: Automatically detects 20+ terminal emulators and uses Ctrl+Shift+V

#include <X11/extensions/XTest.h>

Display *dpy = XOpenDisplay(NULL);

// Press Ctrl
XTestFakeKeyEvent(dpy, XKeysymToKeycode(dpy, XK_Control_L), True, 0);

// Press V
XTestFakeKeyEvent(dpy, XKeysymToKeycode(dpy, XK_v), True, 0);
XTestFakeKeyEvent(dpy, XKeysymToKeycode(dpy, XK_v), False, 0);

// Release Ctrl
XTestFakeKeyEvent(dpy, XKeysymToKeycode(dpy, XK_Control_L), False, 0);

XFlush(dpy);

Compilation (automatic during build):

npm run compile:linux-paste

Detected terminals (auto-uses Ctrl+Shift+V):

gnome-terminal, konsole, kitty, alacritty, wezterm, foot
terminator, tilix, xterm, urxvt, st, yakuake
guake, tilda, hyper, tabby, sakura, warp
termius, ghostty

Fallback Tools (External Dependencies)

If the native binary fails, OpenWhispr falls back to system tools in this order:

X11
Wayland (wlroots)
Wayland (GNOME/KDE)

xdotool (recommended):

# Debian/Ubuntu
sudo apt install xdotool

# Fedora/RHEL
sudo dnf install xdotool

# Arch
sudo pacman -S xdotool

xdotool is the primary fallback for X11. It’s reliable and widely supported.

wtype (for Sway, Hyprland, etc.):

# Debian/Ubuntu
sudo apt install wtype

# Fedora/RHEL
sudo dnf install wtype

# Arch
sudo pacman -S wtype

wtype works best on wlroots-based compositors (Sway, Hyprland, River, Wayfire).

ydotool (universal Wayland solution):

# Debian/Ubuntu
sudo apt install ydotool
sudo systemctl enable --now ydotoold

# Fedora/RHEL
sudo dnf install ydotool
sudo systemctl enable --now ydotoold

# Arch
sudo pacman -S ydotool
sudo systemctl enable --now ydotoold

The ydotoold daemon must be running for ydotool to work. Check with: systemctl status ydotoold

ydotool version compatibility:

0.1.x (Ubuntu 24.04): Uses key names (ctrl+v)
1.0.x (Arch): Uses raw keycodes (29:1, 47:1)

OpenWhispr auto-detects the version and uses the correct syntax.

Recommended Setup by Desktop Environment

Desktop	Recommended Tools	Fallback
X11 (GNOME, KDE, XFCE)	`xdotool`	Native `linux-fast-paste`
GNOME Wayland	Native `linux-fast-paste --portal`	`ydotool` + `ydotoold`
KDE Wayland	Native `linux-fast-paste --portal`	`ydotool` + `ydotoold`
Sway / Hyprland	`wtype`	Native `linux-fast-paste --uinput`
XWayland apps	`xdotool`	Native `linux-fast-paste` (XTest)

Install wl-clipboard for reliable clipboard sharing between Wayland apps:

# Debian/Ubuntu
sudo apt install wl-clipboard

# Fedora/RHEL
sudo dnf install wl-clipboard

# Arch
sudo pacman -S wl-clipboard

GNOME Wayland Global Shortcuts

On GNOME Wayland, Electron’s globalShortcut API doesn’t work. OpenWhispr uses native GNOME shortcuts via D-Bus.

How It Works

OpenWhispr creates a D-Bus service at com.openwhispr.App
Registers a custom GNOME keybinding via gsettings
GNOME triggers dbus-send command when hotkey is pressed
D-Bus service calls the Toggle() method, starting/stopping recording

const { MessageBus } = require('dbus-next');

class GnomeShortcutManager {
  async initDBusService(callback) {
    this.bus = MessageBus.connectSession();
    
    // Register D-Bus interface
    const iface = {
      name: 'com.openwhispr.App',
      methods: {
        Toggle: {
          inSignature: '',
          outSignature: '',
          fn: () => {
            callback();  // Trigger recording
          }
        }
      }
    };
    
    await this.bus.export('/com/openwhispr/App', iface);
    await this.bus.requestName('com.openwhispr.App');
  }
}

Limitations

Push-to-talk mode is NOT available on GNOME Wayland. GNOME shortcuts only fire a single toggle event (no key-up detection).

The app automatically uses tap-to-talk mode on GNOME Wayland.

Hotkey Format Conversion

Electron Format	GNOME Format
`Alt+R`	`<Alt>r`
`Control+Shift+Space`	`<Control><Shift>space`
`CommandOrControl+K`	`<Control>k`
Backtick (`)	`grave`

Viewing Registered Shortcuts

Your OpenWhispr hotkey appears in: GNOME Settings → Keyboard → Keyboard Shortcuts → Custom Shortcuts You can modify or remove it there (the app will re-register on next launch).

Troubleshooting

Text is copied but not pasted automatically

Cause: Missing paste tools or daemon not running.Solution:For X11:

sudo apt install xdotool  # Debian/Ubuntu
sudo dnf install xdotool  # Fedora

For GNOME/KDE Wayland:

sudo apt install ydotool
sudo systemctl enable --now ydotoold
sudo systemctl status ydotoold  # Verify it's running

For Sway/Hyprland:

sudo apt install wtype

Manual paste: Use Ctrl+V (text is always copied to clipboard).

ydotool paste not working

Cause: ydotoold daemon not running.Solution:

# Check daemon status
systemctl status ydotoold

# Start daemon
sudo systemctl start ydotoold

# Enable on boot
sudo systemctl enable ydotoold

# Manual start (alternative)
sudo ydotoold &

Check socket:

ls -la /run/user/$(id -u)/.ydotool_socket

Hotkey not working on GNOME Wayland

Cause: D-Bus service failed to register or gsettings conflict.Check D-Bus service:

dbus-send --session --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames | grep openwhispr

Check registered shortcut:

gsettings get org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/openwhispr/ binding

Reset shortcut:

gsettings reset org.gnome.settings-daemon.plugins.media-keys custom-keybindings

Then restart OpenWhispr.

Terminal paste uses Ctrl+V instead of Ctrl+Shift+V

Cause: Terminal not detected by window class.Check window class:

xdotool getactivewindow getwindowclassname

Solution: Report the terminal name in GitHub Issues to add it to the detection list.Workaround: Manually paste with Ctrl+Shift+V.

Native paste binary compilation failed

Cause: Missing X11 or uinput development headers.Solution:Debian/Ubuntu:

sudo apt install gcc libx11-dev libxtst-dev

Fedora/RHEL:

sudo dnf install gcc libX11-devel libXtst-devel

Arch:

sudo pacman -S gcc libx11 libxtst

Then rebuild:

npm run compile:linux-paste

Microphone not detected

Solution:PulseAudio:

pavucontrol  # Graphical volume control
pactl list sources  # List input devices

PipeWire:

pw-top  # Monitor audio devices
wpctl status  # List devices

Select the correct input device in your desktop sound settings.

Hotkey conflicts with desktop shortcuts

Solution: Change the hotkey in Settings → Hotkeys.Suggested alternatives:

Control+Super (default, may conflict on some DEs)
Control+Shift+K
Super+Shift+R
F8 or F9

Avoid: Super key combinations on GNOME/KDE (often reserved for desktop actions).

Local Whisper models not downloading

Check disk space: Models range from 75MB to 3GB.Models location: ~/.cache/openwhispr/whisper-models/Manual cleanup:

rm -rf ~/.cache/openwhispr/whisper-models

Or use in-app: Settings → General → Remove Downloaded Models

uinput permission denied on Wayland

Cause: User lacks write access to /dev/uinput.Solution:Temporary fix:

sudo chmod 666 /dev/uinput

Permanent fix (add user to input group):

sudo usermod -a -G input $USER

Log out and back in for changes to take effect.udev rule (alternative):

echo 'KERNEL=="uinput", MODE="0660", GROUP="input"' | sudo tee /etc/udev/rules.d/99-uinput.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

Performance Optimization

Local Transcription Performance

Recommended model: base - Best balance of speed and accuracy (~142MB)

Model comparison:

tiny: ~75MB, fastest, lowest quality
base: ~142MB, recommended balance ⭐
small: ~466MB, better quality
medium: ~1.5GB, high quality
large: ~3GB, best quality
turbo: ~1.6GB, fast with good quality

GPU Acceleration

For NVIDIA GPUs, build whisper.cpp with CUDA support:

git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp
make WHISPER_CUDA=1

Replace the bundled binary in resources/bin/whisper-cpp-linux-x64.

Uninstallation

DEB Package
RPM Package
AppImage / TAR.GZ
Flatpak

sudo apt remove openwhispr

The post-remove script automatically cleans up:

~/.cache/openwhispr/whisper-models
Application shortcuts

sudo dnf remove openwhispr
# or
sudo yum remove openwhispr

Simply delete the AppImage or extracted folder.Remove cached models:

rm -rf ~/.cache/openwhispr

flatpak uninstall com.herotools.openwispr

Remove app data:

rm -rf ~/.config/OpenWhispr
rm -rf ~/.local/share/OpenWhispr

Next Steps

Configure Settings

Set up API keys, choose models, and customize hotkeys

Choose Processing Method

Compare local vs cloud transcription options

Troubleshooting Guide

Solutions for common Linux issues

Keyboard Shortcuts

Master hotkeys and activation modes

Get Started

Core Features

Configuration

Platform Guides

Advanced

Linux Installation & Setup

System Requirements

Hardware Requirements

Tested Distributions

Software Requirements

Installation Methods

Clipboard Paste Tools

Native Binary (Primary Method)

Fallback Tools (External Dependencies)

Recommended Setup by Desktop Environment

GNOME Wayland Global Shortcuts

How It Works

Limitations

Hotkey Format Conversion

Viewing Registered Shortcuts

Troubleshooting

Performance Optimization

Local Transcription Performance

GPU Acceleration

Uninstallation

Next Steps

Configure Settings

Choose Processing Method

Troubleshooting Guide

Keyboard Shortcuts

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Platform Guides

Advanced

​System Requirements

​Hardware Requirements

​Tested Distributions

​Software Requirements

​Installation Methods

​Clipboard Paste Tools

​Native Binary (Primary Method)

​Fallback Tools (External Dependencies)

​Recommended Setup by Desktop Environment

​Clipboard Sharing (Wayland)

​GNOME Wayland Global Shortcuts

​How It Works

​Limitations

​Hotkey Format Conversion

​Viewing Registered Shortcuts

​Troubleshooting

​Performance Optimization

​Local Transcription Performance

​GPU Acceleration

​Uninstallation

​Next Steps

Configure Settings

Choose Processing Method

Troubleshooting Guide

Keyboard Shortcuts

Build docs developers (and LLMs) love

System Requirements

Hardware Requirements

Tested Distributions

Software Requirements

Installation Methods

Clipboard Paste Tools

Native Binary (Primary Method)

Fallback Tools (External Dependencies)

Recommended Setup by Desktop Environment

Clipboard Sharing (Wayland)

GNOME Wayland Global Shortcuts

How It Works

Limitations

Hotkey Format Conversion

Viewing Registered Shortcuts

Troubleshooting

Performance Optimization

Local Transcription Performance

GPU Acceleration

Uninstallation

Next Steps