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

> Learn to configure Docker deployment for GPT-SoVITS Lite vs Full variants. Choose your service in docker-compose.yaml or use the build argument for streamlined setup.

- Repository: [RVC-Boss/GPT-SoVITS](https://github.com/RVC-Boss/GPT-SoVITS)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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:

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

```

Alternatively, use the helper script provided in the repository:

```bash
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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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

```bash

# 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

```bash

# 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

```bash

# 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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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`](https://github.com/RVC-Boss/GPT-SoVITS/blob/main/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.