Installation Guide

OpenWhispr supports macOS, Windows, and Linux. Choose your platform below for detailed installation instructions.

System Requirements:

macOS: 10.15 (Catalina) or later, Apple Silicon or Intel
Windows: Windows 10 or later, 64-bit
Linux: Modern distro with glibc 2.31+ (Ubuntu 20.04+, Fedora 32+, etc.)
RAM: 4GB minimum, 8GB recommended for larger models
Disk Space: 500MB for app + 75MB to 3GB for local models

Download OpenWhispr

Get the latest release from GitHub:

Download Latest Release

Visit the GitHub Releases page to download installers for all platforms

Current Version: 1.5.5 (actively maintained)

Platform Installation

macOS
Windows
Linux

macOS Installation

Choose your architecture

Download the appropriate DMG for your Mac:

Apple Silicon (M1, M2, M3, M4): OpenWhispr-{version}-mac-arm64.dmg
Intel: OpenWhispr-{version}-mac-x64.dmg

Not sure? Click Apple menu → About This Mac. If you see “Apple M1” or similar, you have Apple Silicon.

Install the application

Open the downloaded .dmg file
Drag OpenWhispr.app to your Applications folder
Eject the DMG from Finder

First launch (unsigned app)

Since OpenWhispr is not notarized by Apple, you’ll need to bypass Gatekeeper:

Right-click (or Control-click) on OpenWhispr.app in Applications
Select Open from the context menu
Click Open in the security dialog

Do NOT double-click to open the first time. This will show an error. You must right-click → Open to bypass the security warning.

Grant microphone permission

When you first start dictation, macOS will prompt for microphone access:

Click OK to allow microphone access
If you accidentally denied it, go to System Settings → Privacy & Security → Microphone
Enable the checkbox for OpenWhispr

Grant accessibility permission (optional but recommended)

For automatic text pasting, OpenWhispr needs accessibility permission:

Go to System Settings → Privacy & Security → Accessibility
Click the + button (you may need to unlock with your password)
Navigate to Applications and select OpenWhispr
Enable the checkbox for OpenWhispr

Without accessibility permission, transcribed text copies to clipboard. You’ll need to paste manually with Cmd+V.

macOS-Specific Features

Globe Key Support: Optional Fn/Globe key listener for hardware-level dictation trigger
Native AppleScript: Reliable text pasting via AppleScript keystroke
Menu Bar Integration: Clean menu bar icon with quick access to Control Panel
System Settings Links: One-click access to microphone and accessibility settings

Troubleshooting macOS Installation

App is damaged and can't be opened

This happens when trying to double-click on first launch. Solution:

Move OpenWhispr.app to Trash
Re-download and reinstall from DMG
Right-click → Open (not double-click) on first launch

Accessibility permission not working

If text still doesn’t paste after granting accessibility:

Remove OpenWhispr from System Settings → Privacy → Accessibility
Quit OpenWhispr completely (Cmd+Q)
Re-add OpenWhispr to accessibility list
Restart the app

Globe key not working

Globe key requires Xcode Command Line Tools:

# Install Xcode Command Line Tools
xcode-select --install

After installation, restart OpenWhispr.

Windows Installation

Download the installer

Get the NSIS installer:

OpenWhispr-Setup-{version}.exe (64-bit Windows 10+)

Run the installer

Double-click OpenWhispr-Setup-{version}.exe
If SmartScreen appears, click More info → Run anyway
Follow the installation wizard
Choose installation directory (default: C:\Program Files\OpenWhispr)
Click Install

Launch OpenWhispr

After installation:

Launch from Start Menu → OpenWhispr
Or use the Desktop shortcut (if created during install)
System tray icon appears in bottom-right corner

Grant microphone permission

Windows will prompt for microphone access on first use:

Click Allow when prompted
If denied accidentally: Settings → Privacy → Microphone → Enable for OpenWhispr

You can also open microphone settings directly from OpenWhispr’s Control Panel.

Windows-Specific Features

Push-to-Talk: Native low-level keyboard hooks enable true push-to-talk mode
Compound Hotkeys: Full support for multi-key combinations (Ctrl+Shift+F11, etc.)
Terminal Detection: Automatically uses Ctrl+Shift+V in terminals (Windows Terminal, PowerShell, Git Bash, etc.)
Native Paste: Fast SendInput API for instant text pasting
NSIS Installer: Professional installer with uninstall support
Auto-cleanup: Uninstaller removes cached models from %USERPROFILE%\.cache\openwhispr

Alternative Installation Methods

# Download portable ZIP (no installer)
# Extract to any folder
# Run OpenWhispr.exe directly
# Portable version saves settings in app directory

Troubleshooting Windows Installation

SmartScreen blocks installation

Windows SmartScreen may warn about unrecognized app:

Click More info in the SmartScreen dialog
Click Run anyway button that appears
Installation proceeds normally

This happens because OpenWhispr is not code-signed. The app is safe to run.

Push-to-talk not working

Push-to-talk requires the native key listener binary:

Check if windows-key-listener.exe exists in app installation folder
If missing, the app falls back to tap-to-toggle mode
Reinstall OpenWhispr to get the binary

Some antivirus software may flag the key listener binary. This is a false positive.

Text doesn't paste in specific apps

If pasting fails in certain applications:

Text is always copied to clipboard as fallback
Use Ctrl+V to paste manually
Try running the target app as administrator
Check if the app blocks automated input for security

Linux Installation

OpenWhispr supports multiple Linux package formats for maximum compatibility:

AppImage (Universal)
Debian/Ubuntu (.deb)
Fedora/RHEL (.rpm)
Universal Archive (.tar.gz)
Flatpak (Sandboxed)

Best for: Any distro, no root required, portable

Download AppImage

Get the AppImage file:

OpenWhispr-{version}-linux-x64.AppImage

Make executable and run

# Make executable
chmod +x OpenWhispr-*.AppImage

# Run directly
./OpenWhispr-*.AppImage

Optional: Integrate with desktop

# Install AppImageLauncher for desktop integration
# Ubuntu/Debian
sudo apt install appimagelauncher

# Fedora
sudo dnf install appimagelauncher

# Run AppImage again to integrate
./OpenWhispr-*.AppImage

Best for: Debian, Ubuntu, Linux Mint, Pop!_OS, elementary OS

# Download .deb package
# OpenWhispr-{version}-linux-x64.deb

# Install with apt
sudo apt install ./OpenWhispr-*-linux-x64.deb

# Launch from terminal
openwhispr

# Or find in applications menu

Uninstall:

sudo apt remove openwhispr

Best for: Fedora, Red Hat, CentOS, openSUSE, Rocky Linux

# Download .rpm package
# OpenWhispr-{version}-linux-x64.rpm

# Install with dnf
sudo dnf install ./OpenWhispr-*-linux-x64.rpm

# Launch from terminal
openwhispr

# Or find in applications menu

Uninstall:

sudo dnf remove openwhispr

Best for: Any distro, custom installations, server environments

# Download archive
# OpenWhispr-{version}-linux-x64.tar.gz

# Extract
tar -xzf OpenWhispr-*-linux-x64.tar.gz
cd OpenWhispr-*/

# Run directly (no installation)
./openwhispr

# Optional: Create symlink for system-wide access
sudo ln -s "$(pwd)/openwhispr" /usr/local/bin/openwhispr

Best for: Security-focused users, any distro with Flatpak

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

# Install Flatpak runtime (if not already installed)
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# Install OpenWhispr Flatpak
flatpak install --user ./OpenWhispr-*-linux-x64.flatpak

# Run from applications menu or terminal
flatpak run com.herotools.OpenWhispr

Post-Installation: Install Paste Tools

For automatic text pasting, install one of these tools:

X11 (Traditional)
Wayland (Modern)
GNOME Wayland

# Ubuntu/Debian
sudo apt install xdotool

# Fedora/RHEL
sudo dnf install xdotool

# Arch
sudo pacman -S xdotool

OpenWhispr includes a native linux-fast-paste binary that uses XTest extension. xdotool is only needed as fallback.

Option 1: wtype (recommended, requires virtual keyboard protocol)

# Ubuntu/Debian
sudo apt install wtype wl-clipboard

# Fedora/RHEL
sudo dnf install wtype wl-clipboard

# Arch
sudo pacman -S wtype wl-clipboard

Option 2: ydotool (works on more compositors, requires daemon)

# Ubuntu/Debian
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

ydotool requires the ydotoold daemon to be running. Enable it with systemd as shown above.

GNOME Wayland has special requirements:

# Install clipboard tool
sudo apt install wl-clipboard  # Ubuntu/Debian
sudo dnf install wl-clipboard  # Fedora

# For terminal detection on KDE (optional)
sudo apt install kdotool  # Ubuntu/Debian
sudo dnf install kdotool  # Fedora

OpenWhispr uses native GNOME shortcuts via D-Bus on GNOME Wayland. No additional tools needed for hotkey support.

Linux-Specific Features

Native Paste Binary: Uses XTest (X11) or uinput (Wayland) for fast pasting
GNOME Wayland Integration: Native D-Bus shortcuts via gsettings
Terminal Detection: Auto-detects 20+ terminal emulators and uses Ctrl+Shift+V
Multiple Package Formats: AppImage, deb, rpm, tar.gz, Flatpak
XDG Standards: Follows XDG Base Directory specification
Auto-cleanup: Package managers remove cached models on uninstall

System Requirements (Linux)

ldd --version
# Requires glibc 2.31 or later

Troubleshooting Linux Installation

AppImage won't run: No such file or directory

This error indicates missing FUSE:

# Ubuntu/Debian
sudo apt install libfuse2

# Fedora 32+
sudo dnf install fuse-libs

# Arch
sudo pacman -S fuse2

Global hotkey doesn't work on GNOME Wayland

OpenWhispr uses native GNOME shortcuts via D-Bus:

Check Settings → Keyboard → View and Customize Shortcuts → Custom Shortcuts
Look for “OpenWhispr Toggle Dictation”
If missing, restart OpenWhispr
Check logs: journalctl --user -u openwhispr (if installed via package)

Default hotkey on GNOME Wayland is Alt+R (backtick not supported). Push-to-talk is not available.

Text doesn't paste (Wayland)

Ensure you have a paste tool installed:

# Check which tools are available
which wtype ydotool xdotool

# Install missing tools (see tabs above)

# For ydotool, verify daemon is running
systemctl --user status ydotoold

OpenWhispr tries paste methods in this order:

Native linux-fast-paste binary (uinput or XTest)
wtype (Wayland virtual keyboard)
ydotool (Wayland uinput simulator)
xdotool (X11/XWayland apps)
Clipboard fallback (manual Ctrl+V)

Permission denied errors

If you get permission errors:

# Check file permissions
ls -l OpenWhispr-*.AppImage

# Make executable
chmod +x OpenWhispr-*.AppImage

# For uinput access (native paste binary on Wayland)
sudo usermod -aG input $USER
# Log out and back in for group membership to take effect

Post-Installation Setup

After installing, complete the setup process:

Launch OpenWhispr

Open the application from:

macOS: Applications folder or Spotlight
Windows: Start Menu or Desktop shortcut
Linux: Applications menu or terminal (openwhispr)

Complete onboarding

Follow the interactive setup wizard:

Choose authentication (cloud sign-in or skip)
Select processing method (cloud, BYOK, or local)
Configure hotkey
Grant system permissions
Test first transcription

See Quick Start Guide for detailed walkthrough.

Verify installation

Test that everything works:

Press your hotkey (default: backtick `)
Speak: “This is a test”
Press hotkey again
Verify text appears or copies to clipboard

If the dictation panel appears and records audio, your installation is successful!

Building from Source

For developers or users who want to build OpenWhispr from source:

Prerequisites

Install required dependencies:

# Node.js 18+ and npm
# Download from https://nodejs.org

# Verify installation
node --version  # Should be 18.x or higher
npm --version

Platform-specific requirements:

macOS
Windows
Linux

# Xcode Command Line Tools (for Globe key support)
xcode-select --install

# Visual Studio Build Tools or MinGW-w64 (for native binaries)
# Download from: https://visualstudio.microsoft.com/downloads/

# Build tools and X11 development headers
# Ubuntu/Debian
sudo apt install build-essential libx11-dev libxtst-dev

# Fedora/RHEL
sudo dnf install gcc libX11-devel libXtst-devel

# Arch
sudo pacman -S base-devel libx11 libxtst

Clone repository

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

Install dependencies

npm install

Download native binaries

# Download whisper.cpp, llama-server, and sherpa-onnx
npm run download:whisper-cpp
npm run download:llama-server
npm run download:sherpa-onnx

Build and run

Development
Production Build
Distribution

# Run in development mode with hot reload
npm run dev

# Build unsigned package (no code signing)
npm run pack

# Output:
# macOS: dist/mac-arm64/OpenWhispr.app
# Windows: dist/win-unpacked/OpenWhispr.exe
# Linux: dist/linux-unpacked/openwhispr

# Build signed installer (requires certificates)
npm run build:mac    # macOS DMG
npm run build:win    # Windows NSIS installer
npm run build:linux  # Linux AppImage, deb, rpm

Updating OpenWhispr

macOS
Windows
Linux

Download latest DMG from GitHub releases
Drag new version to Applications (replace existing)
Launch updated app

Settings and transcription history are preserved during updates.

Run new installer
Installer automatically updates existing installation
Launch updated app

Cached models and settings are preserved in %USERPROFILE%\.cache\openwhispr.

AppImage: Replace old AppImage with new onePackage managers:

# Debian/Ubuntu
sudo apt install ./OpenWhispr-*-new-version.deb

# Fedora/RHEL
sudo dnf upgrade ./OpenWhispr-*-new-version.rpm

Settings in ~/.config/OpenWhispr/ and models in ~/.cache/openwhispr/ are preserved.

Uninstalling OpenWhispr

macOS
Windows
Linux

Quit OpenWhispr (Cmd+Q)
Move OpenWhispr.app to Trash from Applications folder

Remove settings (optional):

rm -rf ~/Library/Application\ Support/OpenWhispr
rm -rf ~/.cache/openwhispr

Quit OpenWhispr from system tray
Settings → Apps → OpenWhispr → Uninstall
Follow uninstaller wizard

The uninstaller automatically removes cached models from %USERPROFILE%\.cache\openwhispr.

AppImage: Delete the AppImage file and settings:

rm ~/.local/share/applications/openwhispr.desktop  # If integrated
rm -rf ~/.config/OpenWhispr
rm -rf ~/.cache/openwhispr

Package managers:

# Debian/Ubuntu
sudo apt remove openwhispr

# Fedora/RHEL
sudo dnf remove openwhispr

# Flatpak
flatpak uninstall com.herotools.OpenWhispr

Package managers automatically clean up cached models during uninstall.

Next Steps

Quick Start

Complete setup and create your first transcription

Configuration

Customize settings, hotkeys, and processing options

Troubleshooting

Platform-specific issues and solutions

Features

Explore AI processing, custom dictionary, and more

Get Started

Core Features

Configuration

Platform Guides

Advanced

Installation Guide

Installation Guide

Download OpenWhispr

Download Latest Release

Platform Installation

macOS Installation

macOS-Specific Features

Troubleshooting macOS Installation

Windows Installation

Windows-Specific Features

Alternative Installation Methods

Troubleshooting Windows Installation

Linux Installation

Post-Installation: Install Paste Tools

Linux-Specific Features

System Requirements (Linux)

Troubleshooting Linux Installation

Post-Installation Setup

Building from Source

Updating OpenWhispr

Uninstalling OpenWhispr

Next Steps

Quick Start

Configuration

Troubleshooting

Features

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Platform Guides

Advanced

​Installation Guide

​Download OpenWhispr

Download Latest Release

​Platform Installation

​macOS Installation

​macOS-Specific Features

​Troubleshooting macOS Installation

​Windows Installation

​Windows-Specific Features

​Alternative Installation Methods

​Troubleshooting Windows Installation

​Linux Installation

​Post-Installation: Install Paste Tools

​Linux-Specific Features

​System Requirements (Linux)

​Troubleshooting Linux Installation

​Post-Installation Setup

​Building from Source

​Updating OpenWhispr

​Uninstalling OpenWhispr

​Next Steps

Quick Start

Configuration

Troubleshooting

Features

Build docs developers (and LLMs) love

Installation Guide

Download OpenWhispr

Platform Installation

macOS Installation

macOS-Specific Features

Troubleshooting macOS Installation

Windows Installation

Windows-Specific Features

Alternative Installation Methods

Troubleshooting Windows Installation

Linux Installation

Post-Installation: Install Paste Tools

Linux-Specific Features

System Requirements (Linux)

Troubleshooting Linux Installation

Post-Installation Setup

Building from Source

Updating OpenWhispr

Uninstalling OpenWhispr

Next Steps