# How to Set Up OpenSuperWhisper for Docker Deployment > Deploy OpenSuperWhisper on Linux using Docker. Learn to build the C++ inference engine and Python wrapper in a multi-stage Docker image for headless operation. Get it running fast. - Repository: [Starmel/OpenSuperWhisper](https://github.com/Starmel/OpenSuperWhisper) - Tags: how-to-guide - Published: 2026-07-07 --- **OpenSuperWhisper is a macOS menu-bar application that you can containerize for headless Linux deployment by building the C++ inference engine and Python wrapper in a multi-stage Docker image.** OpenSuperWhisper, developed by Starmel, ships as a Swift-based macOS menu-bar utility, but its core transcription logic lives in a portable C++ library. For **OpenSuperWhisper Docker deployment**, you can isolate the Whisper inference engine (`libwhisper`) and expose it via a lightweight Python wrapper, enabling transcription in CI pipelines, servers, or any Linux environment without GUI dependencies. ## Architecture Overview The containerized setup separates the Swift UI from the inference stack. The Docker image compiles the native C++ library from [`libwhisper/CMakeLists.txt`](https://github.com/Starmel/OpenSuperWhisper/blob/main/libwhisper/CMakeLists.txt), installs Python dependencies defined in [`agent/requirements.txt`](https://github.com/Starmel/OpenSuperWhisper/blob/main/agent/requirements.txt), and bundles a [`whisper_cpp.py`](https://github.com/Starmel/OpenSuperWhisper/blob/main/whisper_cpp.py) wrapper that loads the compiled library via `ctypes`. The build process follows a multi-stage pattern: - **Builder stage**: Compiles `libwhisper.a` using CMake and installs Python requirements - **Runtime stage**: Copies the static library, headers, and Python wrapper into a slim Python image - **Model layer**: Includes the `ggml-tiny.en.bin` model file (≈100 MB) at `/models`, with optional bind-mount support for swapping models without rebuilding ## Step 1: Create the Dockerfile Create a `Dockerfile` in your project root that clones the repository and builds the C++ engine. This configuration uses a multi-stage build to keep the final image small. ```dockerfile # -------------------------------------------------------------- # Dockerfile – OpenSuperWhisper (Whisper-only) image # -------------------------------------------------------------- FROM python:3.12-slim AS builder # Install build tools & CMake RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential cmake git && \ rm -rf /var/lib/apt/lists/* # ---------------------------------------------------------------- # Build the libwhisper C++ engine # ---------------------------------------------------------------- WORKDIR /src RUN git clone https://github.com/Starmel/OpenSuperWhisper.git . \ && cd libwhisper \ && cmake -B build -DCMAKE_BUILD_TYPE=Release \ && cmake --build build --config Release # ---------------------------------------------------------------- # Prepare the Python wrapper and install runtime deps # ---------------------------------------------------------------- WORKDIR /app COPY --from=builder /src/agent/requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY --from=builder /src/libwhisper/build/libwhisper.a /usr/local/lib/ COPY --from=builder /src/libwhisper/*.h /usr/local/include/ # Copy the Python wrapper COPY --from=builder /src/agent/whisper_cpp.py /app/ # ---------------------------------------------------------------- # Runtime stage – slimmer image # ---------------------------------------------------------------- FROM python:3.12-slim COPY --from=builder /usr/local/lib/libwhisper.a /usr/local/lib/ COPY --from=builder /usr/local/include/whisper.h /usr/local/include/ COPY --from=builder /app/whisper_cpp.py /app/ COPY --from=builder /src/ggml-tiny.en.bin /models/ggml-tiny.en.bin # Install runtime Python deps COPY --from=builder /app/requirements.txt . RUN pip install --no-cache-dir -r requirements.txt && \ rm requirements.txt ENV MODEL_PATH=/models/ggml-tiny.en.bin ENV LD_LIBRARY_PATH=/usr/local/lib WORKDIR /app ENTRYPOINT ["python", "whisper_cpp.py"] ``` The `ENTRYPOINT` calls the Python wrapper directly, allowing you to pass transcription arguments as command-line flags. ## Step 2: Build the Image Run the following command from the directory containing your `Dockerfile`: ```bash docker build -t opensuperwhisper:latest . ``` This process compiles the C++ library using the CMake configuration in [`libwhisper/CMakeLists.txt`](https://github.com/Starmel/OpenSuperWhisper/blob/main/libwhisper/CMakeLists.txt) and installs the Python dependencies listed in [`agent/requirements.txt`](https://github.com/Starmel/OpenSuperWhisper/blob/main/agent/requirements.txt), including `numpy` and `soundfile`. ## Step 3: Run Transcription Jobs Mount your audio files to `/data` and execute the container. The wrapper accepts the same arguments as the macOS UI's command-line options. ```bash docker run --rm \ -v "$(pwd)/samples:/data" \ -v "$(pwd)/models:/models:ro" \ opensuperwhisper:latest \ --model /models/ggml-tiny.en.bin \ --audio /data/audio.wav \ --language en \ --output /data/output.txt ``` **Key parameters:** - `--model`: Path to the Whisper model binary (default uses `/models/ggml-tiny.en.bin`) - `--audio`: Input audio file path inside the container - `--language`: Target language code (e.g., `en`, `es`) - `--output`: Destination for the transcription text file ## Step 4: Orchestrate with Docker Compose (Optional) For recurring jobs or integration with other services, use Docker Compose. Create a [`docker-compose.yml`](https://github.com/Starmel/OpenSuperWhisper/blob/main/docker-compose.yml) file: ```yaml version: "3.9" services: whisper: image: opensuperwhisper:latest volumes: - ./samples:/data - ./models:/models:ro command: > --model /models/ggml-tiny.en.bin --audio /data/audio.wav --language en --output /data/output.txt ``` Start the transcription job with: ```bash docker compose up ``` ## Model Management and Environment Variables The container expects two environment variables: - **MODEL_PATH**: Default path to the Whisper model binary (set to `/models/ggml-tiny.en.bin` in the Dockerfile) - **LD_LIBRARY_PATH**: Set to `/usr/local/lib` so the Python wrapper can locate `libwhisper.a` via `ctypes` To use a different model (e.g., `ggml-base.en.bin`), download the binary to your host and mount it to `/models` without rebuilding the image: ```bash docker run --rm \ -v "$(pwd)/samples:/data" \ -v "$(pwd)/custom-models:/models:ro" \ opensuperwhisper:latest \ --model /models/ggml-base.en.bin \ --audio /data/audio.wav ``` ## Summary - **OpenSuperWhisper Docker deployment** requires building the C++ inference engine from [`libwhisper/CMakeLists.txt`](https://github.com/Starmel/OpenSuperWhisper/blob/main/libwhisper/CMakeLists.txt) and packaging the Python wrapper from the `agent/` directory. - Use a multi-stage Dockerfile to compile `libwhisper.a` in a builder stage, then copy only the necessary artifacts to a slim Python runtime image. - Mount audio files to `/data` and models to `/models` when running containers. - The [`whisper_cpp.py`](https://github.com/Starmel/OpenSuperWhisper/blob/main/whisper_cpp.py) wrapper loads the native library via `ctypes` and accepts standard Whisper CLI arguments. - For detailed build flags and optimization options, refer to [`docs/build_whisper.md`](https://github.com/Starmel/OpenSuperWhisper/blob/main/docs/build_whisper.md) in the Starmel/OpenSuperWhisper repository. ## Frequently Asked Questions ### Can I run OpenSuperWhisper on Linux without Docker? OpenSuperWhisper is designed as a macOS menu-bar application written in Swift, so the full GUI application only runs on macOS. However, the core Whisper inference engine (`libwhisper`) is cross-platform C++ code that compiles on Linux. The Docker containerization approach described here packages that Linux-compatible inference engine with a Python wrapper, enabling headless operation on any Linux host. ### How do I use a custom Whisper model in the Docker container? The container includes the `ggml-tiny.en.bin` model by default at `/models`. To use a custom model, download the desired GGML model file (e.g., `ggml-base.en.bin`) to your host machine and mount it as a read-only volume to `/models`. Then pass the `--model` flag pointing to the mounted path. This approach avoids rebuilding the Docker image when switching between model sizes. ### Is GPU acceleration supported in the Docker container? The standard Dockerfile provided compiles the CPU-only version of `libwhisper` using the CMake configuration in [`libwhisper/CMakeLists.txt`](https://github.com/Starmel/OpenSuperWhisper/blob/main/libwhisper/CMakeLists.txt). To enable GPU acceleration, you would need to modify the CMake build flags (e.g., adding CUDA or Metal support) and use a base image with the appropriate GPU drivers and runtime libraries. The current implementation targets CPU inference for maximum portability across different Docker hosts. ### How does the Python wrapper communicate with the C++ library? The [`whisper_cpp.py`](https://github.com/Starmel/OpenSuperWhisper/blob/main/whisper_cpp.py) wrapper (located in the `agent/` directory) uses Python's built-in `ctypes` module to load the compiled static library `libwhisper.a` at runtime. It sets `LD_LIBRARY_PATH` to `/usr/local/lib` where the library is installed, then calls the C functions directly. This thin wrapper exposes the same transcription functionality used by the macOS UI but without requiring Swift or AppKit dependencies.