How to Configure Docker Deployment with GPT-SoVITS Lite vs Full Image Variants

GPT-SoVITS provides two Docker image families—a full variant that bundles ASR and UVR5 models and a lite variant that omits them to reduce size—and you configure your deployment by selecting the appropriate service in docker-compose.yaml or by passing the --lite build argument when building locally.

The RVC-Boss/GPT-SoVITS repository offers flexible containerization options for its text-to-speech synthesis toolkit. When you configure Docker deployment with lite versus full image variants, you choose between pre-baked convenience and a minimal footprint that requires manual model management.

Understanding the Lite and Full Image Architectures

Full Image Variant

The full image, tagged as xxxxrt666/gpt-sovits:latest-cu126 or latest-cu128, ships with all optional dependencies including ASR (Automatic Speech Recognition) models and UVR5 (Vocal Remover) weights. According to the source code in docker-compose.yaml (lines 4-24), these services—named GPT-SoVITS-CU126 and GPT-SoVITS-CU128—come ready-to-run without additional volume mounts for model files.

Lite Image Variant

The lite variant uses tags appended with -lite (e.g., latest-cu126-lite) and excludes the heavyweight ASR and UVR5 models to minimize download size and storage footprint. As defined in docker-compose.yaml (lines 22-34), services like GPT-SoVITS-CU126-Lite require you to mount host-side model directories into the container at runtime.

Configuring Docker Compose for Production Deployment

To configure Docker deployment with these variants, modify your service selection and volume mounts in docker-compose.yaml.

Selecting the Service

• Full deployment: Use service names GPT-SoVITS-CU126 or GPT-SoVITS-CU128.
• Lite deployment: Use service names GPT-SoVITS-CU126-Lite or GPT-SoVITS-CU128-Lite.

Volume Requirements for Lite

The lite variant expects specific host mounts that the full variant includes internally. In docker-compose.yaml (lines 33-34 and 71-72), the lite services declare:

• tools/asr/models mounted to /workspace/models/asr_models
• tools/uvr5/uvr5_weights mounted to /workspace/models/uvr5_weights

Shared Memory Configuration

Both variants require elevated shared memory settings. The compose file sets shm_size: "16g" (lines 19, 39, 57, 77), which is mandatory for PyTorch data loaders and particularly critical on Windows Docker hosts.

Building Custom Images with the LITE Build Argument

When building locally instead of pulling pre-built images, the Dockerfile exposes an ARG LITE parameter on lines 20-22 that defaults to false and propagates as an environment variable (ENV LITE=${LITE}).

To generate a lite image locally, pass the build argument:

docker build --build-arg LITE=true -t gpt-sovits:local-lite .

Alternatively, use the helper script provided in the repository:

bash docker_build.sh --cuda 12.6 --lite

This script forwards the --lite flag as --build-arg LITE=true to the Docker build process. When LITE=true, the build skips the model downloads performed by Docker/install_wrapper.sh, resulting in a smaller image that cleans up model directories at container start (lines 52-59 of the Dockerfile).

Deployment Commands and Examples

Pulling and Running the Full Variant

# Pull the full CUDA 12.6 image

docker compose pull GPT-SoVITS-CU126

# Run with ports exposed

docker compose run --service-ports GPT-SoVITS-CU126

Pulling and Running the Lite Variant

# Pull the lite CUDA 12.8 image

docker compose pull GPT-SoVITS-CU128-Lite

# Run with required model mounts (ensure local directories exist)

docker compose run --service-ports GPT-SoVITS-CU128-Lite

Accessing Running Containers

# Enter a running lite container's shell

docker exec -it GPT-SoVITS-CU126-Lite bash

Summary

• Full images (latest-cu126, latest-cu128) bundle ASR and UVR5 models internally and require no additional volume mounts for basic functionality.
• Lite images (latest-cu126-lite, latest-cu128-lite) exclude optional models to reduce size and require mounting tools/asr/models and tools/uvr5/uvr5_weights from the host.
• Configure your deployment by selecting the appropriate service name in docker-compose.yaml: GPT-SoVITS-CU126 for full or GPT-SoVITS-CU126-Lite for lite.
• Build custom lite images by setting --build-arg LITE=true or using docker_build.sh --lite.
• Both variants require shm_size: "16g" in Docker Compose for stable operation.

Frequently Asked Questions

What is the primary difference between the lite and full GPT-SoVITS Docker images?

The full image includes all optional ASR and UVR5 model weights inside the container, while the lite image omits them to reduce the initial download size by several gigabytes. When running the lite variant, you must mount these model directories from your host filesystem into /workspace/models/asr_models and /workspace/models/uvr5_weights.

Can I convert a running lite container to use full capabilities without restarting?

No, the lite versus full distinction is determined at image build time via the LITE build argument and the service definition in docker-compose.yaml. To switch variants, you must stop the container and start a new one using the full service name or image tag.

How do I build a custom lite image for CUDA 12.8?

Execute the build script with the --lite flag specified: bash docker_build.sh --cuda 12.8 --lite. This passes --build-arg LITE=true to the Dockerfile, which then skips the heavyweight model downloads in Docker/install_wrapper.sh and sets the container environment variable LITE=true.

Why does Docker Compose require shm_size: "16g" for both variants?

PyTorch's data loading mechanisms rely on shared memory for inter-process communication during batch processing. The shm_size: "16g" setting in docker-compose.yaml (lines 19, 39, 57, 77) prevents runtime crashes, particularly on Windows Docker Desktop where default shared memory limits are insufficient for GPU-accelerated inference.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}