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.
- 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 useKPipeline(lang_code='a')with voiceaf_heart. - Easiest server:
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest, then openhttp://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
- Create a virtual environment:
python -m venv kokoro-env, then activate it (kokoro-env\Scripts\activateon Windows,source kokoro-env/bin/activateon Mac/Linux). - Install Kokoro:
pip install "kokoro>=0.9.4" soundfile - Install espeak-ng (used for English fallback and some languages):
- Windows: download the latest
.msifrom the espeak-ng GitHub releases and run it. - Ubuntu/Debian:
sudo apt-get install espeak-ng - Mac:
brew install espeak-ng
- Windows: download the latest
- 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) - Run it:
python tts.py. You get one or more WAV files at 24 kHz. - Mac GPU: run with
PYTORCH_ENABLE_MPS_FALLBACK=1 python tts.pyto 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.
- Install Docker (Docker Desktop on Windows/Mac). For NVIDIA GPUs, make sure Docker has GPU access.
- 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(alatest-cu128tag 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
- CPU only:
- Open the web UI:
http://localhost:8880/web. Type text, pick a voice and generate. - API docs:
http://localhost:8880/docs - 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)
- Install:
pip install -U kokoro-onnx soundfile(or with uv:uv add kokoro-onnx soundfile). - Download two files from the kokoro-onnx GitHub releases:
kokoro-v1.0.onnxandvoices-v1.0.bin. Put them next to your script. - Copy the example
examples/save.pyfrom 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.9for calm narration,1.1for 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.




