Installing Kokoro (Docker)

HOW TO INSTALL KOKORO WITH DOCKER

Install Docker

Install Docker Desktop for Windows/Mac or Docker Engine for Linux, if you don't have it yet.

Start the container (quickstart)

A single docker run command. On the very first start, the container automatically downloads the model from Hugging Face (a few hundred MB) and stores it in the volume — after that, later runs start right away.

docker run -p 8000:8000 \
  -v kokoro_cache:/data/hf-cache \
  thorstenvoice/kokoro-tts

As soon as the log shows "Modell geladen und einsatzbereit." (German for "model loaded and ready"), the server is ready.

Alternatively with docker-compose (recommended)

For continuous operation, create a docker-compose.yml:

services:
  thorsten-kokoro-tts:
    image: thorstenvoice/kokoro-tts:latest
    container_name: thorsten-kokoro-tts
    ports:
      - "8000:8000"
    environment:
      - KOKORO_EPOCH=5
    volumes:
      - kokoro_cache:/data/hf-cache
    restart: unless-stopped

volumes:
  kokoro_cache:

and then start it with:

docker compose up -d

GENERATE SPEECH

Once the container is running, you can simply talk to it via HTTP — no SDK, no installation needed on your side. The voice speaks German, so send German text.

Generate speech

Send text via HTTP POST, get a WAV file back.

curl -X POST http://localhost:8000/tts \
     -H "Content-Type: application/json" \
     -d '{"text": "Hallo, ich bin Thorsten. Schön, dass du da bist."}' \
     --output thorsten.wav

Adjust speaking rate

The speed value ranges from 0.0 (exclusive) to 2.0, the default is 1.0.

curl -X POST http://localhost:8000/tts \
     -H "Content-Type: application/json" \
     -d '{"text": "Das hier wird etwas langsamer gesprochen.", "speed": 0.85}' \
     --output output.wav

Check status

Shows whether the server is running and which training checkpoint is currently active.

curl http://localhost:8000/health
# {"status":"ok","repo_id":"Thorsten-Voice/Kokoro","epoch":"5","device":"cpu"}

Choose a different training checkpoint

The KOKORO_EPOCH environment variable lets you switch between epochs 1–10 (default: 5).

docker run -p 8000:8000 \
  -e KOKORO_EPOCH=10 \
  -v kokoro_cache:/data/hf-cache \
  thorstenvoice/kokoro-tts

FAQ & TROUBLESHOOTING

Port 8000 is already in use on my machine ⌄

Simply map a different host port, e.g. -p 8080:8000 instead of -p 8000:8000 (in docker-compose.yml, adjust the ports lines accordingly). The container itself keeps listening on 8000 internally.

Nothing happens for a long time on the first start, the log says something about "Downloading" ⌄

That's normal: the container downloads the Kokoro model from Hugging Face once (a few hundred MB). Depending on your internet connection, this can take a minute or two. Important: the very first start requires an internet connection, even though it runs completely offline afterwards — thanks to the kokoro_cache volume, it won't download again on the next start.

"docker: permission denied" on Linux ⌄

Usually your user lacks permission to talk to the Docker daemon. Either run the command with sudo, or add your user to the docker group once (sudo usermod -aG docker $USER, then log in again).

The container keeps restarting (crash loop) ⌄

Check the logs with docker logs thorsten-kokoro-tts (or the name of your container) — the actual error message is usually there, such as a problem with the model download or a port already in use.

Does this also run on Apple Silicon or an ARM server? ⌄

Yes — the image is published as a multi-arch build for linux/amd64 and linux/arm64 and runs natively on Windows, Mac (Intel & Apple Silicon) and Linux, entirely CPU-based without a GPU.

Installing Thorsten-Voice with Kokoro (Docker)