hwdsl2/kokoro-server repository overview

⁠Kokoro Text-to-Speech on Docker

GitHub: https://github.com/hwdsl2/docker-kokoro⁠

Part of the Self-Hosted AI Stack⁠ — deploy a complete self-hosted AI stack with a single command.

Docker image to run a Kokoro⁠ text-to-speech server. Provides an OpenAI-compatible audio speech API. Based on Debian (python:3.12-slim). Designed to be simple, private, and self-hosted.

Features:

• OpenAI-compatible POST /v1/audio/speech endpoint — any app using the OpenAI TTS API switches with a one-line change
• 54 high-quality voices across 9 languages (English, Japanese, Chinese, Spanish, French, Italian, and more)
• Accepts OpenAI voice-name aliases (alloy, nova, echo, ...) that map to local Kokoro voices, plus native Kokoro voice IDs (af_heart, bm_george, ...)
• Audio stays on your server — no data sent to third parties
• All major output formats supported: mp3, wav, flac, opus, aac, pcm
• Streaming support — set stream_format to "audio" or "sse" to receive audio as each sentence is synthesized, reducing time-to-first-audio
• NVIDIA GPU (CUDA) acceleration for faster inference (:cuda image tag)
• Offline/air-gapped mode — run without internet access using pre-cached model (KOKORO_LOCAL_ONLY)
• Automatically built and published via GitHub Actions⁠
• Persistent model cache via a Docker volume
• Multi-arch: linux/amd64, linux/arm64

Also available:

• Try it online: Open in Colab⁠ — no Docker or installation required
• Related AI services: Whisper⁠, Embeddings⁠, LiteLLM⁠, Ollama⁠, Docling⁠, MCP Gateway⁠

⁠Quick start

Use this command to set up a Kokoro TTS server:

docker run \
    --name kokoro \
    --restart=always \
    -v kokoro-data:/var/lib/kokoro \
    -p 8880:8880 \
    -d hwdsl2/kokoro-server

docker run \
    --name kokoro \
    --restart=always \
    --gpus=all \
    -v kokoro-data:/var/lib/kokoro \
    -p 8880:8880 \
    -d hwdsl2/kokoro-server:cuda

Important: This image requires at least 1.5 GB of available RAM due to the PyTorch runtime and Kokoro model. Systems with 1 GB or less of total RAM are not supported.

Note: For internet-facing deployments, use a reverse proxy⁠ to add HTTPS. Also replace -p 8880:8880 with -p 127.0.0.1:8880:8880 in the docker run command above, to prevent direct access to the unencrypted port.

The Kokoro model (~320 MB) is downloaded and cached on first start. Check the logs to confirm the server is ready:

docker logs kokoro

Once you see "Kokoro text-to-speech server is ready", synthesize your first audio file:

curl http://your_server_ip:8880/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{"model":"tts-1","input":"Hello, world!","voice":"af_heart"}' \
    --output speech.mp3

⁠Community

• 📬 Get project updates and free deployment guides⁠ (1–2 emails/month)
• 💬 Join the r/selfhostedstack⁠ community for discussions and showcases
• ⭐ Star the repository if you find it useful — it helps others discover it

⁠Requirements

• A Linux server (local or cloud) with Docker installed
• Supported architectures: amd64 (x86_64), arm64 (e.g. Raspberry Pi 4/5, AWS Graviton)
• Minimum RAM: ~1.5 GB free (model is ~320 MB; PyTorch runtime uses additional memory)
• Internet access for the initial model download (the model is cached locally afterwards). Not required if using KOKORO_LOCAL_ONLY=true with a pre-cached model.

For GPU acceleration (:cuda image):

• NVIDIA GPU with CUDA support (Compute Capability 6.0+)
• NVIDIA driver⁠ 575.57.08+ (Linux) or 576.57+ (Windows) installed on the host
• NVIDIA Container Toolkit⁠ installed
• The :cuda image supports linux/amd64 only

For internet-facing deployments, see Using a reverse proxy⁠ to add HTTPS.

⁠Download

Get the trusted build from the Docker Hub registry⁠:

docker pull hwdsl2/kokoro-server

For NVIDIA GPU acceleration, pull the :cuda tag instead:

docker pull hwdsl2/kokoro-server:cuda

Alternatively, you may download from Quay.io⁠:

docker pull quay.io/hwdsl2/kokoro-server
docker image tag quay.io/hwdsl2/kokoro-server hwdsl2/kokoro-server

Supported platforms: linux/amd64 and linux/arm64. The :cuda tag supports linux/amd64 only.

⁠Environment variables

All variables are optional. Fresh installs with a mounted /var/lib/kokoro volume auto-generate a Bearer token. Existing installs without a key remain open for backward compatibility.

This Docker image uses the following variables, that can be declared in an env file (see example⁠):

Note: In your env file, you may enclose values in single quotes, e.g. VAR='value'. Do not add spaces around =. If you change KOKORO_PORT, update the -p flag in the docker run command accordingly.

Example using an env file:

cp kokoro.env.example kokoro.env
# Edit kokoro.env with your settings, then:
docker run \
    --name kokoro \
    --restart=always \
    -v kokoro-data:/var/lib/kokoro \
    -v ./kokoro.env:/kokoro.env:ro \
    -p 8880:8880 \
    -d hwdsl2/kokoro-server

The env file is bind-mounted into the container, so changes are picked up on every restart without recreating the container.

docker run \
    --name kokoro \
    --restart=always \
    -v kokoro-data:/var/lib/kokoro \
    -p 8880:8880 \
    --env-file=kokoro.env \
    -d hwdsl2/kokoro-server

⁠Using docker-compose

cp kokoro.env.example kokoro.env
# Edit kokoro.env as needed, then:
docker compose up -d
docker logs kokoro

Example docker-compose.yml (already included):

services:
  kokoro:
    image: hwdsl2/kokoro-server
    container_name: kokoro
    restart: always
    ports:
      - "8880:8880/tcp"  # For a host-based reverse proxy, change to "127.0.0.1:8880:8880/tcp"
    volumes:
      - kokoro-data:/var/lib/kokoro
      - ./kokoro.env:/kokoro.env:ro

volumes:
  kokoro-data:
    name: kokoro-data

Note: For internet-facing deployments, use a reverse proxy⁠ to add HTTPS. Also change "8880:8880/tcp" to "127.0.0.1:8880:8880/tcp" in docker-compose.yml, to prevent direct access to the unencrypted port.

cp kokoro.env.example kokoro.env
# Edit kokoro.env as needed, then:
docker compose -f docker-compose.cuda.yml up -d
docker logs kokoro

services:
  kokoro:
    image: hwdsl2/kokoro-server:cuda
    container_name: kokoro
    restart: always
    ports:
      - "8880:8880/tcp"  # For a host-based reverse proxy, change to "127.0.0.1:8880:8880/tcp"
    volumes:
      - kokoro-data:/var/lib/kokoro
      - ./kokoro.env:/kokoro.env:ro
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  kokoro-data:
    name: kokoro-data

⁠API reference

The API is compatible with OpenAI's text-to-speech endpoint⁠. Any application already calling https://api.openai.com/v1/audio/speech can switch to self-hosted by setting:

OpenAI voice names are accepted as local aliases for client compatibility. These aliases map to Kokoro voices and do not reproduce OpenAI's proprietary voices. The voice field may be a string or an object with an id field; unknown voices return 400.

OPENAI_BASE_URL=http://your_server_ip:8880

⁠Synthesize speech

POST /v1/audio/speech
Content-Type: application/json

Request body:

Example:

curl http://your_server_ip:8880/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{"model":"tts-1","input":"The quick brown fox jumps over the lazy dog.","voice":"af_heart"}' \
    --output speech.mp3

With a different voice and format:

curl http://your_server_ip:8880/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{"model":"tts-1","input":"Hello from London.","voice":"bm_george","response_format":"wav","speed":0.9}' \
    --output speech.wav

With API key authentication:

curl http://your_server_ip:8880/v1/audio/speech \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"model":"tts-1","input":"Hello world","voice":"nova"}' \
    --output speech.mp3

Response: Binary audio data with the appropriate Content-Type header.

⁠List voices

GET /v1/voices

Returns all available Kokoro voice IDs and their OpenAI alias mappings.

curl http://your_server_ip:8880/v1/voices

⁠List models

GET /v1/models

Returns the active models in OpenAI-compatible format.

curl http://your_server_ip:8880/v1/models

⁠Interactive API docs

An interactive Swagger UI is available at:

http://your_server_ip:8880/docs

⁠Available voices

Use kokoro_manage --listvoices to see the full list at any time:

docker exec kokoro kokoro_manage --listvoices

American English:

British English:

Japanese: jf_alpha, jf_gongitsune, jf_nezumi, jf_tebukuro, jm_kumo

Mandarin Chinese: zf_xiaobei, zf_xiaoni, zf_xiaoxiao, zf_xiaoyi, zm_yunjian, zm_yunxi, zm_yunxia, zm_yunyang

Spanish: ef_dora, em_alex, em_santa

French: ff_siwis

Hindi: hf_alpha, hf_beta, hm_omega, hm_psi

Italian: if_sara, im_nicola

Brazilian Portuguese: pf_dora, pm_alex, pm_santa

OpenAI voice aliases (accepted in the voice field):

All voices use a single shared model file (~320 MB). No re-download is needed when switching voices.

⁠Persistent data

All server data is stored in the Docker volume (/var/lib/kokoro inside the container):

/var/lib/kokoro/
├── hub/                           # Cached Kokoro model files (downloaded from HuggingFace)
├── .port                          # Active port (used by kokoro_manage)
├── .voice                         # Active default voice (used by kokoro_manage)
└── .server_addr                   # Cached server IP (used by kokoro_manage)

Back up the Docker volume to preserve the downloaded model. The model is ~320 MB and only needs to be downloaded once.

⁠Managing the server

Use kokoro_manage inside the running container to inspect and manage the server.

Show server info:

docker exec kokoro kokoro_manage --showinfo

List available voices:

docker exec kokoro kokoro_manage --listvoices

⁠Changing the voice

To change the default voice, update KOKORO_VOICE in your kokoro.env file and restart the container. No model re-download is required — all voices use the same Kokoro-82M model.

# Edit kokoro.env: set KOKORO_VOICE=bm_george
docker restart kokoro

⁠Securing your server

See Securing your server⁠.

⁠Using a reverse proxy

For internet-facing deployments, place a reverse proxy in front of the TTS server to handle HTTPS termination. The server works without HTTPS on a local or trusted network, but HTTPS is recommended when the API endpoint is exposed to the internet.

Use one of the following addresses to reach the TTS container from your reverse proxy:

• kokoro:8880 — if your reverse proxy runs as a container in the same Docker network as the TTS server (e.g. defined in the same docker-compose.yml).
• 127.0.0.1:8880 — if your reverse proxy runs on the host and port 8880 is published (the default docker-compose.yml publishes it).

Example with Caddy⁠ (Docker image⁠) (automatic TLS via Let's Encrypt, reverse proxy in the same Docker network):

Caddyfile:

kokoro.example.com {
  reverse_proxy kokoro:8880
}

Example with nginx (reverse proxy on the host):

server {
    listen 443 ssl;
    server_name kokoro.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass         http://127.0.0.1:8880;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }
}

Fresh persistent installs auto-generate a KOKORO_API_KEY. Display it with docker exec kokoro kokoro_manage --showkey, or use docker exec kokoro kokoro_manage --getkey in scripts. For existing installs without a key, set KOKORO_API_KEY in your env file to enable authentication.

⁠Update Docker image

To update the Docker image and container, first download⁠ the latest version:

docker pull hwdsl2/kokoro-server

If the Docker image is already up to date, you should see:

Status: Image is up to date for hwdsl2/kokoro-server:latest

Otherwise, it will download the latest version. Remove and re-create the container:

docker rm -f kokoro
# Then re-run the docker run command from Quick start with the same volume and port.

Your downloaded model is preserved in the kokoro-data volume.

⁠Using with other AI services

Kokoro can be used as the text-to-speech service in a broader self-hosted AI setup.

For full and lightweight Docker Compose stacks, manual docker run examples, and voice/RAG/MCP pipeline examples with Kokoro, Embeddings, LiteLLM, Ollama, Docling, and MCP Gateway, see Self-Hosted AI Stack⁠.

⁠Usage counts

See Usage counts⁠.

⁠Technical details

• Base image: python:3.12-slim (Debian)
• Runtime: Python 3 (virtual environment at /opt/venv)
• TTS engine: Kokoro⁠ (Kokoro-82M, Apache 2.0) with PyTorch (CPU and CUDA GPU)
• API framework: FastAPI⁠ + Uvicorn⁠
• Audio encoding: soundfile⁠ (wav/flac), ffmpeg⁠ (mp3/aac/opus)
• Data directory: /var/lib/kokoro (Docker volume)
• Model storage: HuggingFace Hub format inside the volume — downloaded once, reused on restarts
• Sample rate: 24 kHz (native Kokoro output)

⁠License

Note: The software components inside the pre-built image (such as Kokoro and its dependencies) are under the respective licenses chosen by their respective copyright holders. As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Copyright (C) 2026 Lin Song
This work is licensed under the MIT License⁠.

Kokoro TTS is Copyright (C) hexgrad, and is distributed under the Apache License 2.0⁠.

This project is an independent Docker setup for Kokoro and is not affiliated with, endorsed by, or sponsored by hexgrad or OpenAI.