Izwi runs on most modern Linux distributions. Linux GitHub Release assets keep the public 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:
  • .deb package for Debian/Ubuntu installs
  • AppImage desktop bundle and updater artifact
  • terminal tarball
The public command names stay 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

Download Izwi_<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

For terminal tarballs (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:
This is the development setup: the server is reachable at 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:
In a second terminal:
For source builds, 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:
Create /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:
Check status:

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

  1. Verify NVIDIA drivers are installed:
  2. If you installed from source, ensure CUDA toolkit is in your PATH:
  3. If you installed from source, rebuild with CUDA:
  4. 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:

Next Steps