Skip to content
,

How to Run Kokoro TTS Locally: Free AI Voice With Python, Docker and Web UI (2026)

6–10 minutes
Smiling woman in a teal turtleneck holding a KOKORO card in a greenhouse, hook text: Free AI voice, no cloud

Kokoro is one of the best free text-to-speech models you can run on your own computer. It is tiny (82 million parameters), sounds natural, runs fast even on a CPU, and its Apache 2.0 licence lets you use it in personal and commercial projects.

That makes it a great free alternative to paid voice services for narration, audiobooks, YouTube voiceovers, screen readers and voice assistants, with no per-character fees and nothing leaving your PC.

This guide shows four ways to run Kokoro locally: the official Python library, the lightweight ONNX version, the Kokoro-FastAPI server with a web UI and OpenAI-compatible API, and one-click apps.

You will also learn which voices sound best, how to pick languages, and how to fix common errors. Details come from the official hexgrad/kokoro repo, the Kokoro-82M model card and the Kokoro-FastAPI and kokoro-onnx READMEs, checked in November 2026.

TL;DR

  • Model: Kokoro-82M v1.0 (Jan 2025), Apache 2.0, 54 voices, American and British English plus Spanish, French, Hindi, Italian, Japanese, Brazilian Portuguese and Mandarin.
  • Python: pip install "kokoro>=0.9.4" soundfile, install espeak-ng, then use KPipeline(lang_code='a') with voice af_heart.
  • Easiest server: docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest, then open http://localhost:8880/web.
  • NVIDIA GPU: docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest
  • Light option: pip install -U kokoro-onnx (about 300 MB model, 80 MB quantised).
  • Best voices: af_heart (grade A), af_bella (A-), then af_nicole, bf_emma and ff_siwis.
  • Output: 24 kHz audio.

What Is Kokoro TTS?

Kokoro is an open-weight text-to-speech model by hexgrad. Its model card says it delivers quality comparable to much larger models while being faster and cheaper to run.

Spec Kokoro-82M
Parameters 82 million
Latest version v1.0 (27 January 2025)
Voices 54
Languages American English, British English, Spanish, French, Hindi, Italian, Japanese, Brazilian Portuguese, Mandarin Chinese
Licence Apache 2.0 (commercial use allowed)
Architecture StyleTTS 2 + ISTFTNet, decoder only
Training data A few hundred hours of permissive, non-copyrighted audio
Sample rate 24 kHz

Kokoro does not clone voices from a short sample by itself. It speaks with its built-in voices, which you can mix. Community tools add custom voice packs on top.

Which Way Should You Run It?

Method Best for Needs
Official Python library Scripts, batch audio, developers Python, espeak-ng
Kokoro-FastAPI Web UI, OpenAI-compatible API, other apps Docker (or uv)
kokoro-onnx Small, fast, CPU-friendly apps Python, ONNX Runtime
Apps (KoboldCpp, Open WebUI via API) No-code users The app

Requirements

  • CPU: any modern CPU works. Kokoro is small enough for near real-time on many machines.
  • GPU (optional): NVIDIA with CUDA speeds up long generations. Apple Silicon can use MPS. AMD ROCm is experimental in Kokoro-FastAPI.
  • RAM: 4 GB free is plenty.
  • Disk: about 300 MB for the model, more for Docker images.
  • Python: 3.10 to 3.12 is the safest range for most TTS libraries.

Method 1: Official Python Library

  1. Create a virtual environment: python -m venv kokoro-env, then activate it (kokoro-env\Scripts\activate on Windows, source kokoro-env/bin/activate on Mac/Linux).
  2. Install Kokoro: pip install "kokoro>=0.9.4" soundfile
  3. Install espeak-ng (used for English fallback and some languages):
    • Windows: download the latest .msi from the espeak-ng GitHub releases and run it.
    • Ubuntu/Debian: sudo apt-get install espeak-ng
    • Mac: brew install espeak-ng
  4. Save this as tts.py:
    from kokoro import KPipeline
    import soundfile as sf
    
    pipeline = KPipeline(lang_code='a')  # 'a' = American English
    text = "Hello! This voice was generated locally with Kokoro."
    for i, (gs, ps, audio) in enumerate(pipeline(text, voice='af_heart', speed=1)):
        sf.write(f'out_{i}.wav', audio, 24000)
  5. Run it: python tts.py. You get one or more WAV files at 24 kHz.
  6. Mac GPU: run with PYTORCH_ENABLE_MPS_FALLBACK=1 python tts.py to use Apple Silicon acceleration.

Long text is split into chunks (by default on new lines with split_pattern=r'\n+'), so each paragraph becomes its own file. Join them with any audio editor or a small script.

For Japanese and Mandarin, install the extra phonemiser packages: pip install misaki[ja] or pip install misaki[zh].

Method 2: Kokoro-FastAPI (Web UI + API)

Kokoro-FastAPI wraps Kokoro in a Docker server with a web interface and an OpenAI-compatible speech endpoint, so any app that speaks OpenAI’s TTS API can use it.

  1. Install Docker (Docker Desktop on Windows/Mac). For NVIDIA GPUs, make sure Docker has GPU access.
  2. Start it:
    • CPU only: 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 (a latest-cu128 tag is available for newer CUDA)
    • AMD GPU (experimental, Linux x86_64): docker run --device=/dev/kfd --device=/dev/dri -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-rocm:latest
  3. Open the web UI: http://localhost:8880/web. Type text, pick a voice and generate.
  4. API docs: http://localhost:8880/docs
  5. Use it from Python with the OpenAI SDK:
    from openai import OpenAI
    client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")
    resp = client.audio.speech.create(model="kokoro", voice="af_bella+af_sky",
                                      input="Hello world!", response_format="mp3")
    resp.write_to_file("hello.mp3")

Kokoro-FastAPI also offers voice mixing (like af_bella+af_sky), SSML, per-word timestamps for captions, and ElevenLabs- and Cartesia-compatible websockets for voice agents. On Apple Silicon, run it natively with its start-gpu_mac.sh script for MPS speed, because the GPU Docker image is CUDA only.

New to Docker for AI? Our Ollama in Docker guide covers GPU setup that works the same way here.

Method 3: kokoro-onnx (Lightweight)

  1. Install: pip install -U kokoro-onnx soundfile (or with uv: uv add kokoro-onnx soundfile).
  2. Download two files from the kokoro-onnx GitHub releases: kokoro-v1.0.onnx and voices-v1.0.bin. Put them next to your script.
  3. Copy the example examples/save.py from the repo into your script and run it.

The ONNX model is about 300 MB (about 80 MB quantised) and runs near real-time on an M1 Mac. It is ideal for bundling TTS into your own desktop app.

Method 4: Apps That Include Kokoro

  • KoboldCpp: supports Kokoro for text-to-speech out of the box; load a Kokoro TTS GGUF. See our KoboldCpp guide.
  • Open WebUI: point its audio settings at Kokoro-FastAPI’s OpenAI-compatible endpoint (http://localhost:8880/v1) to make your local chatbot talk. Setup in our Open WebUI + Ollama guide.
  • SillyTavern and voice-agent frameworks (LiveKit, Pipecat) connect through Kokoro-FastAPI.
  • Online demo: the official Hugging Face Space (hexgrad/Kokoro-TTS) lets you test voices before installing.

Voices and Languages

Voice names follow a simple pattern: first letter = language, second letter = gender (f/m), then a name. For example, af_heart is an American English female voice.

Language lang_code Voices (F/M) Example
American English a 11 / 9 af_heart, af_bella, am_michael
British English b 4 / 4 bf_emma, bm_george
Spanish e 1 / 2 ef_dora
French f 1 / 0 ff_siwis
Hindi h 2 / 2 hf_alpha
Italian i 1 / 1 if_sara
Japanese j 4 / 1 jf_alpha
Brazilian Portuguese p 1 / 2 pf_dora
Mandarin Chinese z 4 / 4 zf_xiaobei

Top-graded voices in the official VOICES list: af_heart (A), af_bella (A-), then af_nicole, bf_emma and ff_siwis (B-). Always match lang_code to the voice’s first letter, or pronunciation goes wrong.

Tips for Natural Speech

  • Write for the ear: short sentences and commas where you would pause.
  • Spell out tricky items: “two thousand twenty-six” or “AI” vs “A.I.” if a number or acronym sounds odd.
  • Fix names with phonemes: the library accepts inline pronunciations in the form [Kokoro](/kˈOkəɹO/).
  • Adjust speed: speed=0.9 for calm narration, 1.1 for snappy videos.
  • Mix voices in Kokoro-FastAPI (af_bella+af_sky) for a unique sound.
  • Use one paragraph per line so the default splitter makes clean chunks.

Need the reverse, speech to text? Pair Kokoro with Whisper using our run Whisper locally guide. Comparing paid voices? See our ElevenLabs alternatives roundup.

Troubleshooting

Problem Likely cause Fix
espeak / phonemizer error espeak-ng not installed or not on PATH Install espeak-ng (MSI on Windows), restart the terminal
Wrong accent or garbled words lang_code doesn’t match voice Use ‘a’ with af_/am_ voices, ‘b’ with bf_/bm_, etc.
Japanese/Chinese fails Missing language extras pip install misaki[ja] or misaki[zh]
Slow on Mac Running on CPU Set PYTORCH_ENABLE_MPS_FALLBACK=1, or use kokoro-onnx
Docker GPU image won’t start No NVIDIA GPU access in Docker Install NVIDIA Container Toolkit / enable GPU in Docker Desktop, or use the CPU image
Port 8880 in use Another app on that port Map another port, e.g. -p 8890:8880
pip install fails Python too new for a dependency Use Python 3.10 to 3.12 in a fresh venv
Many small WAV files Text split on new lines Join files, or change split_pattern
Robotic pauses Very long sentences Break text into shorter sentences

My Take

For free local TTS, Kokoro is the first thing I would try. It is small, fast, sounds natural with af_heart or af_bella, and the Apache licence means no worries for YouTube or commercial projects.

If you just want to type and listen, run the Kokoro-FastAPI Docker image and open the web UI. If you build apps, the OpenAI-compatible endpoint or kokoro-onnx makes it a drop-in replacement for paid TTS APIs.

FAQ

Is Kokoro TTS free?

Yes. The model is open weight under Apache 2.0, free for personal and commercial use.

Can Kokoro run without a GPU?

Yes. At 82M parameters it runs well on a CPU. A GPU only speeds up long jobs.

Can Kokoro clone my voice?

Not by itself. It uses 54 built-in voices that you can mix. Community tools add custom voice packs.

Which Kokoro voice sounds best?

af_heart has the top grade (A), followed by af_bella (A-). bf_emma is the best-rated British voice.

Does Kokoro support Hindi?

Yes. Use lang_code='h' with one of the four Hindi voices.

Can I use Kokoro with the OpenAI API format?

Yes. Kokoro-FastAPI serves an OpenAI-compatible endpoint at http://localhost:8880/v1.

What audio format does Kokoro output?

24 kHz audio. The Python library returns raw audio you save as WAV; Kokoro-FastAPI can return MP3 and other formats.

Sources

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Smiling woman in a teal turtleneck holding a KOKORO card in a greenhouse, hook text: Free AI voice, no cloud