hwdsl2/whisper-server

Whisper Speech-to-Text on Docker

https://github.com/hwdsl2/docker-whisper/actions/workflows/main.yml/badge.svg](https://github.com/hwdsl2/docker-whisper/actions/workflows/main.yml)  https://raw.githubusercontent.com/hwdsl2/badges/main/img/docker-pulls-whisper-server.svg](https://hub.docker.com/r/hwdsl2/whisper-server)  ![Open In Colab]([***]

GitHub: https://github.com/hwdsl2/docker-whisper

Part of the https://github.com/hwdsl2/docker-ai-stack — deploy a complete self-hosted AI stack with a single command.

Docker image to run a https://github.com/openai/whisper speech-to-text server, powered by https://github.com/SYSTRAN/faster-whisper. Provides OpenAI-compatible audio transcription and translation APIs. Based on Debian (python:3.12-slim). Designed to be simple, private, and self-hosted.

Features:

• OpenAI-compatible POST /v1/audio/transcriptions and POST /v1/audio/translations endpoints — any app using the OpenAI Whisper API switches with a one-line change
• Supports all Whisper models: tiny, base, small, medium, large-v3, large-v3-turbo and more
• Speaker diarization — identify who is speaking in each segment (optional, via https://github.com/k2-fsa/sherpa-onnx)
• Model management via a helper script (whisper_manage)
• Audio stays on your server — no data sent to third parties
• All major audio formats supported (mp3, m4a, wav, webm, ogg, flac, and all ffmpeg formats)
• Multiple response formats: JSON, plain text, verbose JSON, SRT subtitles, WebVTT subtitles
• Streaming transcription — add stream=true to receive segments via SSE as they are decoded, with no waiting for the full file
• NVIDIA GPU (CUDA) acceleration for faster inference (:cuda image tag)
• Offline/air-gapped mode — run without internet access using pre-cached models (WHISPER_LOCAL_ONLY)
• Automatically built and published via https://github.com/hwdsl2/docker-whisper/actions/workflows/main.yml
• 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
• AI/Audio: https://github.com/hwdsl2/docker-whisper-live, https://github.com/hwdsl2/docker-kokoro, https://github.com/hwdsl2/docker-embeddings, https://github.com/hwdsl2/docker-litellm, https://github.com/hwdsl2/docker-ollama, https://github.com/hwdsl2/docker-docling
• : https://github.com/hwdsl2/docker-, https://github.com/hwdsl2/docker-open***, https://github.com/hwdsl2/docker-ipsec-***-server, https://github.com/hwdsl2/docker-***
• Tools: https://github.com/hwdsl2/docker-mcp-gateway

Tip: Whisper, Kokoro, Embeddings, LiteLLM, Ollama, Docling, and MCP Gateway can be used together to build a complete, self-hosted AI stack on your own server.

Community

• Subscribe for project updates (1–2 emails/month) — get free AI and *** deployment guides (PDF)
• Join the r/selfhostedstack community for discussions and showcases

When to use Whisper vs. WhisperLive

Quick start

Use this command to set up a Whisper server:

bash
docker run \
    --name whisper \
    --restart=always \
    -v whisper-data:/var/lib/whisper \
    -p 9000:9000 \
    -d hwdsl2/whisper-server

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

Important: This image requires at least 700 MB of available RAM for the default base model. Systems with 512 MB or less of RAM are not supported.

Note: For internet-facing deployments, using a reverse proxy to add HTTPS is strongly recommended. In that case, also replace -p 9000:9000 with -p 127.0.0.1:9000:9000 in the docker run command above, to prevent direct access to the unencrypted port. Set WHISPER_API_KEY in your env file when the server is accessible from the public internet.

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

bash
docker logs whisper

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

bash
curl http://your_server_ip:9000/v1/audio/transcriptions \
    -F file=@audio.mp3 \
    -F model=whisper-1

Response:

json
{"text": "Your transcribed text appears here."}

Tip: Need a sample audio file to test? Download this English speech sample (WAV, MIT License) from the https://github.com/Azure-Samples/cognitive-services-speech-sdk repository:

bash
curl -L -o sample_speech.wav \
    "https://github.com/Azure-Samples/cognitive-services-speech-sdk/raw/master/sampledata/audiofiles/katiesteve.wav"

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -F file=@sample_speech.wav \
    -F model=whisper-1

Alternatively, you may https://github.com/hwdsl2/whisper-install. To learn more about how to use this image, read the sections below.

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: ~700 MB free for the default base model (see model table)
• Internet access for the initial model download (the model is cached locally afterwards). Not required if using WHISPER_LOCAL_ONLY=true with pre-cached models.

For GPU acceleration (:cuda image):

• NVIDIA GPU with CUDA support (Compute Capability 6.0+)
• NVIDIA driver 535 or later 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 https://hub.docker.com/r/hwdsl2/whisper-server/:

bash
docker pull hwdsl2/whisper-server

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

bash
docker pull hwdsl2/whisper-server:cuda

Alternatively, you may download from Quay.io:

bash
docker pull quay.io/hwdsl2/whisper-server
docker image tag quay.io/hwdsl2/whisper-server hwdsl2/whisper-server

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

Environment variables

All variables are optional. Set WHISPER_API_KEY to enable Bearer token authentication.

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 WHISPER_PORT, update the -p flag in the docker run command accordingly.

Example using an env file:

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

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

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

Using docker-compose

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

Example docker-compose.yml (already included):

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

volumes:
  whisper-data:
    name: whisper-data

Note: For internet-facing deployments, using a reverse proxy to add HTTPS is strongly recommended. In that case, also change "9000:9000/tcp" to "127.0.0.1:9000:9000/tcp" in docker-compose.yml, to prevent direct access to the unencrypted port. Set WHISPER_API_KEY in your env file when the server is accessible from the public internet.

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

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

volumes:
  whisper-data:
    name: whisper-data

API reference

The API is fully compatible with OpenAI's audio transcription and audio translation endpoints. Any application already calling https://api.openai.com/v1/audio/transcriptions can switch to self-hosted by setting:

OPENAI_BASE_URL=http://your_server_ip:9000

Transcribe audio

POST /v1/audio/transcriptions
Content-Type: multipart/form-data

Parameters:

Example:

bash
curl http://your_server_ip:9000/v1/audio/transcriptions \
    -F file=@meeting.m4a \
    -F model=whisper-1 \
    -F language=en

With API key authentication:

bash
curl http://your_server_ip:9000/v1/audio/transcriptions \
    -H "Authorization: Bearer your_api_key" \
    -F file=@audio.mp3 \
    -F model=whisper-1

Response formats

See https://github.com/hwdsl2/docker-whisper#response-formats for more details.

Translate audio

POST /v1/audio/translations
Content-Type: multipart/form-data

Translates audio in any language to English text. Drop-in replacement for OpenAI's audio translation endpoint. Accepts the same parameters as the transcription endpoint. The output is always in English.

Note: Translation is not supported with English-only (.en) models. Use a multilingual model (e.g. base, small, large-v3-turbo).

Example:

bash
curl http://your_server_ip:9000/v1/audio/translations \
    -F file=@french_audio.mp3 \
    -F model=whisper-1

List models

GET /v1/models

Returns the active model in OpenAI-compatible format.

bash
curl http://your_server_ip:9000/v1/models

Interactive API docs

An interactive Swagger UI is available at:

http://your_server_ip:9000/docs

Persistent data

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

/var/lib/whisper/
├── models--Systran--faster-whisper-*/   # Cached Whisper model files (downloaded from HuggingFace)
├── .port                 # Active port (used by whisper_manage)
├── .model                # Active model name (used by whisper_manage)
└── .server_addr          # Cached server IP (used by whisper_manage)

Back up the Docker volume to preserve downloaded models. Models are large (145 MB – 3 GB) and can take several minutes to download on first start; preserving the volume avoids re-downloading on container recreation.

Tip: The /var/lib/whisper volume uses the same HuggingFace cache layout as docker-whisper-live's /var/lib/whisper-live volume. If you have already downloaded a model with docker-whisper-live, you can bind-mount the same volume directory to avoid re-downloading.

Managing the server

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

Show server info:

bash
docker exec whisper whisper_manage --showinfo

List available models:

bash
docker exec whisper whisper_manage --listmodels

Pre-download a model:

bash
docker exec whisper whisper_manage --downloadmodel large-v3-turbo

Switching models

To change the active model:

1. (Optional but recommended) Pre-download the new model while the server is running:

   bash
   docker exec whisper whisper_manage --downloadmodel large-v3-turbo
   

2. Update WHISPER_MODEL in your whisper.env file (or add -e WHISPER_MODEL=large-v3-turbo to your docker run command).

3. Restart the container:

   bash
   docker restart whisper
   

Available models:

Tip: large-v3-turbo offers accuracy close to large-v3 at roughly half the resource cost. It is the recommended upgrade path from base for most production deployments.

RAM figures are approximate and reflect INT8 quantization (default). Models are cached in the /var/lib/whisper Docker volume and only downloaded once.

Using a reverse proxy

For internet-facing deployments, place a reverse proxy in front of Whisper 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 Whisper container from your reverse proxy:

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

Example with Caddy (https://hub.docker.com/_/caddy) (automatic TLS via Let's Encrypt, reverse proxy in the same Docker network):

Caddyfile:

whisper.example.com {
  reverse_proxy whisper:9000
}

Example with nginx (reverse proxy on the host):

nginx
server {
    listen 443 ssl;
    server_name whisper.example.com;

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

    # Audio files can be large — increase the upload limit as needed
    client_max_body_size 100M;

    location / {
        proxy_pass         http://127.0.0.1:9000;
        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_http_version 1.1;       # required for chunked streaming (SSE)
        proxy_read_timeout 300s;
    }
}

Set WHISPER_API_KEY in your env file when the server is accessible from the public internet.

Update Docker image

See https://github.com/hwdsl2/docker-whisper#update-docker-image.

Using with other AI services

See https://github.com/hwdsl2/docker-whisper#using-with-other-ai-services.

Speaker diarization

Speaker diarization identifies who is speaking in each transcribed segment. It is powered by https://github.com/k2-fsa/sherpa-onnx using the pyannote segmentation-3.0 model exported to ONNX format.

Enable diarization:

bash
# In your whisper.env:
WHISPER_DIARIZATION=true

ONNX models (~45 MB total) are automatically downloaded on first use and cached in the /var/lib/whisper volume. To pre-download them:

bash
docker exec whisper whisper_manage --downloaddiarize

Output with diarization enabled:

verbose_json adds a speaker field to each segment:

json
{
  "segments": [
    {"id": 0, "start": 1.0, "end": 3.5, "text": "We should launch next week.", "speaker": "SPEAKER_00"},
    {"id": 1, "start": 4.0, "end": 6.2, "text": "I think QA needs two more days.", "speaker": "SPEAKER_01"}
  ]
}

srt and vtt prepend the speaker label:

1
00:00:01,000 --> 00:00:03,500
[SPEAKER_00] We should launch next week.

2
00:00:04,000 --> 00:00:06,200
[SPEAKER_01] I think QA needs two more days.

text format shows the speaker label on speaker changes:

[SPEAKER_00] We should launch next week.
[SPEAKER_01] I think QA needs two more days.

Notes:

• Diarization requires full audio analysis and is not supported in streaming mode (stream=true). If both are enabled, diarization is silently skipped.
• Set WHISPER_DIARIZE_NUM_SPEAKERS if you know the exact number of speakers for better accuracy.
• The diarization pipeline runs after transcription, adding a small amount of processing time proportional to audio duration.

Technical details

• Base image: python:3.12-slim (Debian) for :latest; nvidia/cuda:12.9.1-cudnn-runtime-ubuntu24.04 for :cuda
• Runtime: Python 3 (virtual environment at /opt/venv)
• STT engine: https://github.com/SYSTRAN/faster-whisper with CTranslate2 (INT8 by default on CPU, FP16 on CUDA)
• API framework: FastAPI + Uvicorn
• Audio decoding: https://github.com/PyAV-Org/PyAV (bundled FFmpeg libraries)
• Data directory: /var/lib/whisper (Docker volume)
• Model storage: HuggingFace Hub format inside the volume — downloaded once, reused on restarts

License

Note: The software components inside the pre-built image (such as faster-whisper 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.

faster-whisper is Copyright (C) SYSTRAN, and is distributed under the https://github.com/SYSTRAN/faster-whisper/blob/master/LICENSE.

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