izwi and izwi-server names and are intentionally CPU-only.
See the Runtime Support Matrix for the current artifact contract.
Requirements
- Ubuntu 20.04+, Debian 11+, Fedora 36+, or similar
- 8 GB RAM minimum (16 GB recommended)
- 10 GB free disk space (more for models)
- NVIDIA GPU (optional, for CUDA acceleration)
Install from GitHub Releases
Linux release surfaces are CPU-only native artifacts:.debpackage for Debian/Ubuntu installs- AppImage desktop bundle and updater artifact
- terminal tarball
izwi and izwi-server. CUDA runtime libraries and CUDA-linked binaries are not bundled in native Linux release artifacts.
Install from .deb Package (Debian/Ubuntu)
The .deb package is CPU-only. Use Docker CUDA or a source build when you need NVIDIA acceleration.
Step 1: Download
DownloadIzwi_<version>_amd64.deb from the Releases page.
Step 2: Install
apt installs the package’s dependencies for you. The package installs izwi and izwi-server to /usr/bin.
Step 3: Verify
izwi-cli-v<version>-linux-x86_64.tar.gz), unpack the release archive and keep the bundled binaries together.
With the AppImage (Izwi_<version>_amd64.AppImage), open Settings > System > Command line tool and select Install to copy izwi to ~/.local/bin (Izwi adds that folder to your PATH in ~/.profile if needed; open a new shell afterwards).
Optional: Install espeak-ng for Kokoro-82M
Kokoro-82M uses espeak-ng for phonemization. Install it before using Kokoro voices.
Ubuntu / Debian
Fedora
Arch Linux
Verify
Install from Source
Prerequisites
./scripts/install-cli.sh also builds the web UI and the desktop app, so you need Node.js 24.15+ or 22.22+ (with npm) and the Tauri system libraries.
Install Rust
Build Izwi
CUDA Support (NVIDIA GPUs)
Native Linux GitHub Release artifacts are CPU-only. For CUDA-capable binaries on NVIDIA Linux hosts, use the Docker CUDA profile:http://localhost:8080 from this machine only and needs no API key. For production (an API key, publishing beyond loopback), see Docker.
The image targets Ampere (compute capability 8.0) and newer GPUs. To build for another architecture, set CUDA_COMPUTE_CAP (for example CUDA_COMPUTE_CAP=90) when you build.
Source Build CUDA Path
Source builds still require a CUDA toolkit.Step 1: Install CUDA Toolkit
Step 2: Build with CUDA
Step 3: Verify CUDA
Start the server in one terminal:izwi version --full should include CUDA under Compiled Backends. Runtime selection still comes from izwi status --detailed.
Data Locations
Running as a Service
Create a systemd service for automatic startup:/etc/izwi/izwi.env (readable only by the service user) containing
IZWI_API_KEY=<a long random key>, or drop --host 0.0.0.0 and the
EnvironmentFile line to keep the server on loopback.
Replace YOUR_USERNAME with your actual username, then:
Uninstall
From .deb Package
From Source
Remove Data (Optional)
Troubleshooting
Permission denied when binding to port 8080
Either use a higher port or run with elevated privileges:CUDA not detected
-
Verify NVIDIA drivers are installed:
-
If you installed from source, ensure CUDA toolkit is in your PATH:
-
If you installed from source, rebuild with CUDA:
-
Verify the runtime:
Audio playback not working
izwi tts --play plays the saved file with an external player. Install one of paplay (pulseaudio-utils), aplay (alsa-utils), ffplay (ffmpeg) or play (sox):
Kokoro error: espeak-ng not found
Install espeak-ng with your distro package manager, then verify: