macOS Installation

Izwi is optimized for macOS with native Apple Silicon (M1/M2/M3/M4) acceleration via Metal.

Requirements

macOS 12.0 (Monterey) or later
8 GB RAM minimum (16 GB recommended)
10 GB free disk space (more for models)

Install from DMG (Recommended)

Step 1: Download

Download the latest Izwi-*.dmg from GitHub Releases.

Step 2: Install

Open the downloaded .dmg file
Drag Izwi.app into your Applications folder
Eject the disk image

Step 3: First Launch

Open Izwi from Applications
If prompted about an unidentified developer:
- Go to System Settings → Privacy & Security
- Click Open Anyway next to the Izwi message
On first launch, Izwi will:
- Create the ~/.local/bin directory if needed
- Link izwi and izwi-server to your PATH
- May prompt for administrator access

Step 4: Verify

Open Terminal and run:

izwi version --full

Optional: Install `espeak-ng` for Kokoro-82M

Kokoro-82M uses espeak-ng for phonemization. Install it before using Kokoro voices.

Install with Homebrew

brew install espeak-ng

Verify

espeak-ng --version

Install via Homebrew (Coming Soon)

brew install --cask izwi

Command-Line Only Installation

If you only need the CLI tools without the desktop app:

# Clone the repository
git clone https://github.com/izwi-ai/izwi.git
cd izwi

# Build and install with Metal support
IZWI_BUILD_BACKEND=metal ./scripts/install-cli.sh

This installs izwi, izwi-server, and izwi-desktop to ~/.local/bin.

Apple Silicon Optimization

Izwi automatically selects the best backend on Apple Silicon Macs. To explicitly force Metal:

izwi serve --backend metal

Or set the environment variable:

export IZWI_BACKEND=metal
izwi serve

Data Locations

Data	Location
Models	`~/Library/Application Support/izwi/models/`
Config	`~/Library/Application Support/izwi/config.toml`
Logs	`~/Library/Application Support/izwi/logs/`
Cache	`~/Library/Caches/com.agentem.izwi.desktop/`

Uninstall

Quick Uninstall

From a cloned repository:

./scripts/uninstall-macos.sh

Or download the uninstall script from releases:

chmod +x uninstall-izwi-macos.sh
./uninstall-izwi-macos.sh

Manual Uninstall

# Stop any running processes
pkill -f "izwi-server|izwi serve|izwi-desktop" 2>/dev/null || true

# Remove the app
sudo rm -rf "/Applications/Izwi.app"

# Remove CLI tools
sudo rm -f /opt/homebrew/bin/izwi /opt/homebrew/bin/izwi-server
sudo rm -f /usr/local/bin/izwi /usr/local/bin/izwi-server

# Remove data (optional - this deletes your models!)
rm -rf "$HOME/Library/Application Support/izwi"
rm -rf "$HOME/Library/Application Support/com.agentem.izwi.desktop"
rm -rf "$HOME/Library/Caches/com.agentem.izwi.desktop"
rm -rf "$HOME/Library/Saved Application State/com.agentem.izwi.desktop.savedState"
rm -rf "$HOME/Library/WebKit/com.agentem.izwi.desktop"

Verify Removal

command -v izwi || echo "izwi removed"
pgrep -af "izwi" || echo "no izwi processes running"

Troubleshooting

”Izwi can’t be opened because it is from an unidentified developer”

Go to System Settings → Privacy & Security
Scroll down to find the Izwi message
Click Open Anyway

Command not found: izwi

The CLI tools may not be in your PATH. Add this to your ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then reload:

source ~/.zshrc

Kokoro error: `espeak-ng not found`

Install espeak-ng:

brew install espeak-ng
espeak-ng --version

Metal acceleration not working

Ensure you’re on Apple Silicon and running macOS 12.0+:

# Check your chip
uname -m  # Should show "arm64"

# Check macOS version
sw_vers

Home

Reference & Help

macOS Installation

Requirements

Install from DMG (Recommended)

Step 1: Download

Step 2: Install

Step 3: First Launch

Step 4: Verify

Optional: Install `espeak-ng` for Kokoro-82M

Install with Homebrew

Verify

Install via Homebrew (Coming Soon)

Command-Line Only Installation

Apple Silicon Optimization

Data Locations

Uninstall

Quick Uninstall

Manual Uninstall

Verify Removal

Troubleshooting

”Izwi can’t be opened because it is from an unidentified developer”

Command not found: izwi

Kokoro error: `espeak-ng not found`

Metal acceleration not working

Next Steps

​Requirements

​Install from DMG (Recommended)

​Step 1: Download

​Step 2: Install

​Step 3: First Launch

​Step 4: Verify

​Optional: Install espeak-ng for Kokoro-82M

​Install with Homebrew

​Verify

​Install via Homebrew (Coming Soon)

​Command-Line Only Installation

​Apple Silicon Optimization

​Data Locations

​Uninstall

​Quick Uninstall

​Manual Uninstall

​Verify Removal

​Troubleshooting

​”Izwi can’t be opened because it is from an unidentified developer”

​Command not found: izwi

​Kokoro error: espeak-ng not found

​Metal acceleration not working

​Next Steps

Requirements

Install from DMG (Recommended)

Step 1: Download

Step 2: Install

Step 3: First Launch

Step 4: Verify

Optional: Install `espeak-ng` for Kokoro-82M

Install with Homebrew

Verify

Install via Homebrew (Coming Soon)

Command-Line Only Installation

Apple Silicon Optimization

Data Locations

Uninstall

Quick Uninstall

Manual Uninstall

Verify Removal

Troubleshooting

”Izwi can’t be opened because it is from an unidentified developer”

Command not found: izwi

Kokoro error: `espeak-ng not found`

Metal acceleration not working

Next Steps