Build Izwi from source for development, backend-specific installs, or to customize your setup. See the Runtime Support Matrix before choosing a build target. In particular:
  • GitHub Release artifacts and source builds do not expose the same backend set.
  • Metal is the primary accelerated source-build path on Apple Silicon.
  • CUDA source builds are useful for development, custom validation, and fallback debugging. Linux and Windows GitHub Release artifacts are CPU-only; the CUDA distribution path is the Docker CUDA image/profile on NVIDIA Linux hosts.

​
Prerequisites

​
All Platforms

  • Git — Version control
  • Rust — 1.83 or later (stable). CI and Docker builds use current stable Rust; the Docker CPU builder currently uses Rust 1.88.
  • Node.js — 18+ for UI development. Release CI uses Node 20, while the Docker UI builder currently uses Node 24.
  • espeak-ng (optional, required only for Kokoro-82M TTS)
Treat Rust 1.83 and Node 18 as minimums. If you are reproducing release or Docker behavior exactly, use the toolchain versions from the release workflow or Dockerfile.

​
macOS

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

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

​
Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y build-essential curl git pkg-config libssl-dev

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

​
Windows

  1. Install Visual Studio Build Tools
    • Select “Desktop development with C++”
  2. Install Rust
  3. Install Git

​
Clone the Repository

git clone https://github.com/izwi-ai/izwi.git
cd izwi
If you plan to use Kokoro-82M, install espeak-ng using your platform guide before running TTS:

​
Build

The install script builds the CLI, server, and desktop binaries together and makes the backend choice explicit: 
./scripts/install-cli.sh
Backend-specific examples: 
# CPU-focused build
IZWI_BUILD_BACKEND=cpu ./scripts/install-cli.sh

# Apple Silicon / Metal build
IZWI_BUILD_BACKEND=metal ./scripts/install-cli.sh

# NVIDIA CUDA build
IZWI_BUILD_BACKEND=cuda ./scripts/install-cli.sh
On Linux, the script defaults to cpu. On Apple Silicon macOS, it defaults to metal.

​
Manual Cargo Builds

If you only want specific binaries, use package-scoped commands: 
# CPU-focused CLI + server
cargo build --release -p izwi-cli
cargo build --release -p izwi-server

# Metal-capable CLI (macOS)
cargo build --release -p izwi-cli --features metal

# CUDA-capable CLI + server
cargo build --release -p izwi-cli --features cuda
cargo build --release -p izwi-server --features cuda
For Whisper CUDA experiments, source builds can add Candle-backed CUDA features such as flash-attn or cudnn, for example cargo build --release -p izwi-server --features cuda,flash-attn. Only enable cudnn when the matching cuDNN development and runtime libraries are installed.

​
Install UI Dependencies

The web UI requires Node.js: 
cd ui
npm install
cd ..

​
Build the UI

Required for desktop app builds. The UI must be built before compiling izwi-desktop: 
cd ui
npm run build
cd ..

​
Install CLI Tools

​
Using the Install Script

./scripts/install-cli.sh
This installs to ~/.local/bin:
  • izwi — Main CLI
  • izwi-server — API server
  • izwi-desktop — Desktop application
Verify the resulting backend support with: 
izwi version --full
After you start the server with izwi serve, run izwi status --detailed to confirm which backend the runtime actually selected.

​
Manual Installation

# Create directory
mkdir -p ~/.local/bin

# Copy binaries
cp target/release/izwi ~/.local/bin/
cp target/release/izwi-server ~/.local/bin/
cp target/release/izwi-desktop ~/.local/bin/

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

​
Development Mode

​
Run Server in Dev Mode

cargo run --bin izwi-server

​
Run UI in Dev Mode

In a separate terminal: 
cd ui
npm run dev
The dev UI runs at http://localhost:5173 and proxies API requests to the server.

​
Run with Hot Reload

# Install cargo-watch
cargo install cargo-watch

# Run with auto-reload
cargo watch -x "run --bin izwi-server"

​
Project Structure

izwi/
├── crates/
│   ├── izwi-cli/      # CLI application
│   ├── izwi-core/     # Core inference engine
│   ├── izwi-server/   # HTTP API server
│   └── izwi-desktop/  # Tauri desktop app
├── ui/                # React web interface
├── docs/              # Documentation
├── scripts/           # Build and install scripts
└── data/              # Sample data files

​
Running Tests

# Run all tests
cargo test

# Run specific crate tests
cargo test -p izwi-core

# Run with output
cargo test -- --nocapture

​
Building Release Packages

​
macOS DMG

cd crates/izwi-desktop
cargo tauri build
Output: target/release/bundle/dmg/Izwi_*.dmg

​
Linux DEB

cd crates/izwi-desktop
cargo tauri build
Output: target/release/bundle/deb/izwi_*.deb

​
Windows Installer

cd crates/izwi-desktop
cargo tauri build
Output: target/release/bundle/nsis/Izwi_*-setup.exe

​
Troubleshooting

​
Rust version too old

rustup update stable
rustup default stable

​
Missing OpenSSL (Linux)

sudo apt install -y libssl-dev pkg-config

​
Metal not available (macOS)

Ensure you’re on Apple Silicon and macOS 12.0+: 
uname -m  # Should show "arm64"

​
CUDA build fails

Ensure CUDA toolkit is installed and nvcc is in PATH: 
nvcc --version

​
frontendDist path doesn’t exist

If you see this error when building: 
error: proc macro panicked
  --> crates/izwi-desktop/src/main.rs
   |
   |         .build(tauri::generate_context!())
   |                ^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = help: message: The `frontendDist` configuration is set to `"../../ui/dist"` but this path doesn't exist
Build the UI first: 
cd ui
npm install
npm run build
cd ..
Then retry the build.

​
Next Steps