Run Kokoro-82M Locally — Free Open-Source TTS Guide

What Is Kokoro-82M

Kokoro-82M is an open-source text-to-speech model by hexgrad, built on an improved StyleTTS 2 architecture. With 82 million parameters — about 1/100 the size of a typical LLM — it delivers speech quality that beats models 14× larger on the TTS Spaces Arena benchmark.

The model is trained on less than 100 hours of audio data (total training cost: ~$1,000 on an A100), yet achieves state-of-the-art results. It's released under Apache 2.0, meaning you can use it commercially, deploy it in products, or run it entirely offline.

Why Kokoro Matters

How to Install & Run Kokoro-82M

Method 1: Python pip (Quickest)

# 1. Install dependencies
pip install kokoro>=0.9.4 soundfile

# 2. Install espeak-ng (REQUIRED)
# Ubuntu/Debian:
sudo apt-get install espeak-ng

# macOS:
brew install espeak-ng

# Windows: download from github.com/espeak-ng/espeak-ng/releases
# Add to PATH. See FAQ for troubleshooting.

from kokoro import KPipeline
import soundfile as sf

pipeline = KPipeline(lang_code='a')  # 'a' = American English

text = "Hello world! Kokoro is running locally on my machine."
generator = pipeline(text, voice='af_heart', speed=1.0)

for i, (gs, ps, audio) in enumerate(generator):
    sf.write(f'output_{i}.wav', audio, 24000)  # 24kHz sample rate
    print(f"Generated segment {i}")

Method 2: ONNX (Cross-platform, No espeak-ng)

ONNX path eliminates the espeak-ng dependency entirely — smaller model files (q4 quantized: ~305 MB) and runs in the browser via kokoro-js + Transformers.js.

pip install kokoro-onnx soundfile

from kokoro_onnx import Kokoro
kokoro = Kokoro("kokoro-v1.0.onnx", "voices.json")
samples, sample_rate = kokoro.create(
    "Life is like a box of chocolates.",
    voice="af_sarah",
    speed=1.0
)

import soundfile as sf
sf.write("output.wav", samples, sample_rate)

Browser usage:

import { KokoroTTS } from "kokoro-js";
const tts = await KokoroTTS.from_pretrained(
    "onnx-community/Kokoro-82M-ONNX", { dtype: "q4" }
);
const audio = await tts.generate("Hello from your browser!", {
    voice: "af_heart"
});

Method 3: Docker (Kokoro-FastAPI)

The most popular community deployment. Pre-built images for CPU, NVIDIA GPU, AMD ROCm, and Apple Silicon.

# CPU-only (any machine)
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

# NVIDIA GPU
docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

# Test the API
curl -X POST http://localhost:8880/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model": "kokoro", "input": "Kokoro is running via FastAPI.", "voice": "af_heart"}' \
  --output speech.mp3

Features: OpenAI-compatible /v1/audio/speech endpoint, voice mixing, per-word timestamps, phoneme endpoints.

Method 4: Open WebUI Integration

# Deploy Kokoro Web (one command)
docker run -p 3000:3000 ghcr.io/remsky/kokoro-web:latest

In Open WebUI → Admin Settings → Audio → TTS Settings:

• TTS Engine: OpenAI
• API Base URL: http://localhost:3000/api/v1
• API Key: any-string
• TTS Model: kokoro
• TTS Voice: af_heart

54 Voices Overview

Voice naming: af_* = American Female (14 voices), am_* = American Male (8), bf_* = British Female (8), bm_* = British Male (4). Plus Spanish, French, Hindi, Italian, Japanese, Portuguese, Mandarin.

Voice Blending

Create custom voices by blending existing ones with weighted combinations:

# Blend 50% bella + 50% sarah
generator = pipeline(text, voice='af_bella', voice2='af_sarah', voice2_weight=0.5)

Popular community blends:

• af_bella × 0.3 + af_sarah × 0.7 — Warm, professional narration
• af_heart × 0.5 + am_adam × 0.5 — Gender-neutral podcast voice
• af_nicole × 0.4 + am_michael × 0.6 — Energetic tutorial voice

Production Deployment

Architecture:

Docker Compose (CPU)

# docker-compose.yml
services:
  kokoro:
    image: ghcr.io/remsky/kokoro-fastapi-cpu:latest
    ports:
      - "8880:8880"
    environment:
      - DEFAULT_VOICE=af_heart
      - DEFAULT_LANG=a
    restart: unless-stopped

HF 429 Fix — Local Model Caching

If deploying on cloud (GCP, AWS Lambda), you'll hit HuggingFace rate limits. Cache model files locally:

# Pre-download model files (do once)
pip install huggingface_hub
python -c "
from huggingface_hub import snapshot_download
snapshot_download('hexgrad/Kokoro-82M', local_dir='./kokoro_model')
"

# Set environment variables in deployment:
export HF_HOME=/path/to/cached/models
export HF_HUB_OFFLINE=1  # After caching, go fully offline

FAQ

def chunk_text(text, max_chars=400):
    sentences = text.replace('\n', ' ').split('. ')
    chunks, current = [], ""
    for s in sentences:
        if len(current) + len(s) < max_chars:
            current += s + '. '
        else:
            chunks.append(current.strip())
            current = s + '. '
    if current:
        chunks.append(current.strip())
    return chunks

for i, chunk in enumerate(chunk_text(long_text)):
    generator = pipeline(chunk, voice='af_heart')
    for _, _, audio in generator:
        sf.write(f'chapter_{i}.wav', audio, 24000)