English | 简体中文 | 繁體中文 | Русский

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

Docker image to run a Whisper speech-to-text server, powered by 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 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 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
• AI/Audio: WhisperLive (real-time STT), Kokoro (TTS), Embeddings, LiteLLM, Ollama (LLM), Docling
• VPN: WireGuard, OpenVPN, IPsec VPN, Headscale
• Tools: 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 VPN deployment guides (PDF)
• 💬 Join the r/selfhostedstack community for discussions and showcases
• ⭐ Star the repository if you find it useful — it helps others discover it

When to use Whisper vs. WhisperLive

Quick start

Use this command to set up a Whisper server:

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

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:

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

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

Response:

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

Tip: Need a sample audio file to test? Download this English speech sample (WAV, MIT License) from the Azure Samples repository:

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 set up Whisper without Docker. 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 Docker Hub registry:

docker pull hwdsl2/whisper-server

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

docker pull hwdsl2/whisper-server:cuda

Alternatively, you may download from Quay.io:

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:

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.

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

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):

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.

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

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:

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

With API key authentication:

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

Example — stream segments as they are decoded:

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

SSE response (uses the OpenAI streaming transcription protocol):

data: {"type":"transcript.text.delta","delta":"Hello, how are you?"}

data: {"type":"transcript.text.delta","delta":" I'm doing well, thank you."}

data: {"type":"transcript.text.done","text":"Hello, how are you? I'm doing well, thank you."}

data: [DONE]

The first delta typically arrives within 1–3 seconds of upload. Each transcript.text.delta event contains the incremental text for the segment just decoded. The final transcript.text.done event contains the full assembled transcript, equivalent to the standard json response.

const form = new FormData();
form.append("file", audioBlob, "audio.webm");
form.append("model", "whisper-1");
form.append("stream", "true");

const res = await fetch("http://your_server_ip:9000/v1/audio/transcriptions", {
  method: "POST", body: form,
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  // SSE frames are separated by "\n\n"; split and process complete frames
  const frames = buffer.split("\n\n");
  buffer = frames.pop(); // keep any incomplete trailing frame
  for (const frame of frames) {
    if (!frame.startsWith("data: ")) continue;
    const payload = frame.slice(6);
    if (payload.startsWith("[DONE]")) break;
    const event = JSON.parse(payload);
    if (event.type === "transcript.text.delta") console.log(event.delta);
    if (event.type === "transcript.text.done") console.log("Full text:", event.text);
  }
}

Example — get SRT subtitles:

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -F file=@video.mp4 \
    -F model=whisper-1 \
    -F response_format=srt

Example — verbose JSON with timestamps:

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

Example — verbose JSON with word-level timestamps:

curl http://your_server_ip:9000/v1/audio/transcriptions \
    -F file=@audio.mp3 \
    -F model=whisper-1 \
    -F response_format=verbose_json \
    -F "timestamp_granularities[]=word"

When timestamp_granularities[] includes word, the verbose_json response includes a top-level words array:

{
  "word": "hello",
  "start": 0.5,
  "end": 0.8,
  "probability": 0.98
}

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:

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

List models

Returns the active model in OpenAI-compatible format.

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:

docker exec whisper whisper_manage --showinfo

List available models:

docker exec whisper whisper_manage --listmodels

Pre-download a model:

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:

   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:

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.

Securing your server

If your Whisper server is reachable from the public internet — even briefly — apply at minimum these protections. Whisper is CPU/GPU-intensive, so an unauthenticated endpoint can be abused to burn your compute resources.

1. Set an API key. Generate a strong random key and set WHISPER_API_KEY in your env file. All requests must then include Authorization: Bearer <key>.

# Generate a 32-byte random key
openssl rand -hex 32

2. Bind to localhost when fronted by a reverse proxy. Replace -p 9000:9000 with -p 127.0.0.1:9000:9000 (or change "9000:9000/tcp" to "127.0.0.1:9000:9000/tcp" in docker-compose.yml) so the unencrypted port is not reachable directly from outside the host.

3. Limit upload size at the proxy. Audio files can be large; configure your reverse proxy to reject oversized uploads (e.g. nginx client_max_body_size 100M;). This bounds the disk and memory footprint of a single request.

4. Mind the log level. WHISPER_LOG_LEVEL=DEBUG may write transcript text to logs. Keep it at INFO or higher on shared systems.

5. Enable CORS at the proxy if calling from a browser. The server does not set Access-Control-Allow-Origin headers by default; add them at your reverse proxy if you intend to call the API directly from a web page on a different origin.

6. Consider rate limiting. Place a rate-limit (e.g. nginx limit_req_zone, Caddy rate_limit) in front of the server to cap concurrent transcriptions per client IP.

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 (Docker image) (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):

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

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

docker pull hwdsl2/whisper-server

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

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

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

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

Your downloaded models are preserved in the whisper-data volume.

Using with other AI services

The Whisper (STT), Embeddings, LiteLLM, Kokoro (TTS), Ollama (LLM), Docling, and MCP Gateway images can be combined to build a complete, self-hosted AI stack on your own server — from voice I/O to RAG-powered question answering. Whisper, Kokoro, and Embeddings run fully locally. Ollama runs all LLM inference locally, so no data is sent to third parties. When using LiteLLM with external providers (e.g., OpenAI, Anthropic), your data will be sent to those providers.

See also: Docker AI Stack — deploy the full stack with a single command, with ready-made configurations and pipeline examples.

Speaker diarization

Speaker diarization identifies who is speaking in each transcribed segment. It is powered by sherpa-onnx using the pyannote segmentation-3.0 model exported to ONNX format.

Enable diarization:

# 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:

docker exec whisper whisper_manage --downloaddiarize

Output with diarization enabled:

verbose_json adds a speaker field to each segment:

{
  "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: faster-whisper with CTranslate2 (INT8 by default on CPU, FP16 on CUDA)
• API framework: FastAPI + Uvicorn
• Audio decoding: 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 MIT License.

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