Build from Source

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

Install Visual Studio Build Tools
- Select “Desktop development with C++”
Install Rust
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

Recommended: Use the Install Script

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. The repository’s Cargo configuration includes a stable-Rust workaround for Candle 0.11.0 on Apple Silicon. Keep .cargo/config.toml in the checkout and avoid replacing its target flags with a workspace-wide RUSTFLAGS value; release, debug, and test profiles are configured to work together.

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

Tauri installer bundles include the release CLI and server binaries as bundled resources, so build those binaries before running cargo tauri build. If you chain the commands, use && so Tauri does not continue after a failed binary build.

macOS DMG

cargo build --release --features metal --bin izwi --bin izwi-server &&
cargo tauri build --bundles dmg

Output: target/release/bundle/dmg/Izwi_*.dmg

Linux DEB

cargo build --release --bin izwi --bin izwi-server &&
cargo tauri build --bundles deb

Output: target/release/bundle/deb/izwi_*.deb

Windows Installer

cargo build --release --bin izwi --bin izwi-server
cargo tauri build --bundles nsis

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.

Home

Reference & Help

Build from Source

Prerequisites

All Platforms

macOS

Linux (Ubuntu/Debian)

Windows

Clone the Repository

Build

Recommended: Use the Install Script

Manual Cargo Builds

Install UI Dependencies

Build the UI

Install CLI Tools

Using the Install Script

Manual Installation

Development Mode

Run Server in Dev Mode

Run UI in Dev Mode

Run with Hot Reload

Project Structure

Running Tests

Building Release Packages

macOS DMG

Linux DEB

Windows Installer

Troubleshooting

Rust version too old

Missing OpenSSL (Linux)

Metal not available (macOS)

CUDA build fails

frontendDist path doesn’t exist

Next Steps

​Prerequisites

​All Platforms

​macOS

​Linux (Ubuntu/Debian)

​Windows

​Clone the Repository

​Build

​Recommended: Use the Install Script

​Manual Cargo Builds

​Install UI Dependencies

​Build the UI

​Install CLI Tools

​Using the Install Script

​Manual Installation

​Development Mode

​Run Server in Dev Mode

​Run UI in Dev Mode

​Run with Hot Reload

​Project Structure

​Running Tests

​Building Release Packages

​macOS DMG

​Linux DEB

​Windows Installer

​Troubleshooting

​Rust version too old

​Missing OpenSSL (Linux)

​Metal not available (macOS)

​CUDA build fails

​frontendDist path doesn’t exist

​Next Steps

Prerequisites

All Platforms

macOS

Linux (Ubuntu/Debian)

Windows

Clone the Repository

Build

Recommended: Use the Install Script

Manual Cargo Builds

Install UI Dependencies

Build the UI

Install CLI Tools

Using the Install Script

Manual Installation

Development Mode

Run Server in Dev Mode

Run UI in Dev Mode

Run with Hot Reload

Project Structure

Running Tests

Building Release Packages

macOS DMG

Linux DEB

Windows Installer

Troubleshooting

Rust version too old

Missing OpenSSL (Linux)

Metal not available (macOS)

CUDA build fails

frontendDist path doesn’t exist

Next Steps