Skip to content

Docker

Jump to bottom
Vladimir Mandic edited this page May 13, 2026 · 21 revisions

Docker

SD.Next includes base Dockerfiles for these platforms:

Other systems may require different base images or configuration, but the overall approach is the same.

The goal of containerized SD.Next is a stateless environment that is easy to deploy and scale.

It is recommended to build your own image if you need custom extensions or local changes.

The build process is usually fast: around 1 minute for incremental builds and longer for the first build while base images and dependencies download.

If you want to skip local builds, use Prebuilt images from community members (best effort support).

Prerequisites

Important

If you already have functional Docker on your host, you can skip this section
See-also: Manual-Install example

Build Image

First build will also need to download the base image, which can take a while depending on your connection
If you make changes to Dockerfile or update SD.Next, you will need to rebuild the image

Important

Build process should be done on a system where SD.Next was started at least once to download all required submodules before docker copy process

[!TIP] If you want to include any extensions in the docker image, install/clone them into /extensions folder before building the image

CUDA

SD.Next docker template is based on official base image with python==3.11.11, torch==2.8.0 and cuda==12.8
Base image pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime is 3.99GB
And full SD.Next resulting image is ~11.0GB and contains all required dependencies

SD_FOLDER=/home/sdnext # path to sdnext home folder
docker build \
  --debug \
  --tag sdnext/sdnext-cuda \
  --progress=plain \
  --file $SD_FOLDER/configs/Dockerfile.cuda \
  $SD_FOLDER

ROCm

Base image rocm/dev-ubuntu-24.04 is 3.15GB
And full SD.Next resulting image is ~23.15GB and contains all required dependencies

SD_FOLDER=/home/sdnext # path to sdnext home folder
docker build \
  --debug \
  --tag sdnext/sdnext-rocm \
  --progress=plain \
  --file $SD_FOLDER/configs/Dockerfile.rocm \
  $SD_FOLDER

IPEX

Base image https://hub.docker.com/_/ubuntu is 1.1GB
And full SD.Next resulting image is ~9.1GB and contains all required dependencies

SD_FOLDER=/home/sdnext # path to sdnext home folder
docker build \
  --debug \
  --tag sdnext/sdnext-ipex \
  --progress=plain \
  --file $SD_FOLDER/configs/Dockerfile.ipex \
  $SD_FOLDER

OpenVINO

Base image https://hub.docker.com/_/ubuntu is 1.1GB
And full SD.Next resulting image is ~3.6GB

SD_FOLDER=/home/sdnext # path to sdnext home folder
docker build \
  --debug \
  --tag sdnext/sdnext-openvino \
  --progress=plain \
  --file $SD_FOLDER/configs/Dockerfile.openvino \
  $SD_FOLDER

Prebuilt

SD.Next community members have provided prebuilt docker images for various platforms:

  • nVidia CUDA
    tag: vladmandic/sdnext-cuda:latest compressed size: 3.98GB
  • AMD ROCm
    tag: disty0/sdnext-rocm:latest compressed size: 1.05GB
  • Intel IPEX
    tag: disty0/sdnext-ipex:latest compressed size: 0.4GB
  • OpenVINO
    tag: disty0/sdnext-openvino:latest compressed size: 0.4GB

Operating System Support

The SD.Next container can be run on any OS that supports Docker and provides GPU routing to the container

Tip

Note that some OS may further limit the access to hardware resources
In that case, it is recommended to add --privileged to give the container full access to system resources.

Log Example

[+] Building 54.1s (12/12) FINISHED                                                                   docker:default
 => [internal] load build definition from Dockerfile.cuda                                                   0.0s
 => => transferring dockerfile: 2.24kB                                                                      0.0s
 => [internal] load metadata for docker.io/pytorch/pytorch:2.6.0-cuda12.6-cudnn9-runtime                    0.2s
 => [internal] load .dockerignore                                                                           0.0s
 => => transferring context: 366B                                                                           0.0s
 => [1/7] FROM docker.io/pytorch/pytorch:2.6.0-cuda12.6-cudnn9-runtime@sha256:xxx                           0.0s
 => [internal] load build context                                                                           0.1s
 => => transferring context: 279.77kB                                                                       0.1s
 => CACHED [2/7] RUN ["apt-get", "-y", "update"]                                                            0.0s
 => CACHED [3/7] RUN ["apt-get", "-y", "install", "git", "build-essential", "google-perftools", "curl"]     0.0s
 => CACHED [4/7] RUN ["/usr/sbin/ldconfig"]                                                                 0.0s
 => CACHED [5/7] COPY . /app                                                                                0.0s
 => CACHED [6/7] WORKDIR /app                                                                               0.0s
 => [7/7] RUN ["python", "/app/launch.py", "--debug", "--uv", "--use-cuda", "--test", "--optional"]        51.0s
 => exporting to image                                                                                      2.8s
 => => exporting layers                                                                                     2.8s
 => => writing image sha256:xxx                                                                             0.0s
 => => naming to docker.io/sdnext/sdnext-cuda                                                               0.0s

State

As noted above, SD.Next Docker deployment is designed for stateless operation.
By default, any data stored inside the container is lost when the container stops.

All state items and outputs will be read from and written to /server/data
This includes:

  • Configuration files: config.json, ui-config.json
  • Cache information: cache.json, metadata.json
  • Outputs of all generated images: outputs/

Persistence

If you plan to customize SD.Next with additional extensions,
create and mount a Docker volume to avoid repeated reinstall steps on each startup.

Healthchecks

By default, SD.Next docker container does not include Docker healthchecks, but they can be enabled. Remove the comment from the HEALTHCHECK line in Dockerfile and rebuild the image.

Run Local

Containers built using above commands are local and can be used directly on the host system

Note

This is an EXAMPLE run command, modify as needed for your environment!

  • Republishes port from container to host directly
    You may need to remap ports if you have multiple containers running on the same host
  • Maps local server folder /server/data to be used by the container as data root
    This is where all state items and outputs will be read from and written to
  • Maps local server folder /server/models to be used by the container as model root
    This is where models will be read from and written to
  • Locations /mnt/data and /mnt/models are configured inside Dockerfile itself,
    so either edit those values and rebuild container or make sure those are available
  • If you're using network attached storage instead of local folders,
    you can use those directly and skip mounting local folders
docker run \
  --name sdnext-container \
  --rm \
  --gpus all \
  --publish 7860:7860 \
  --mount type=bind,source=/server/models,target=/mnt/models \
  --mount type=bind,source=/server/data,target=/mnt/data \
  --detach \
  sdnext/sdnext-cuda

Warning

Parameter --gpus all is required to expose nVidia CUDA GPU from parent host to the container
For other platforms, use refer to official documentation and use appropriate parameters
For example, AMD uses --device /dev/dri and --device /dev/kfd

[!TIP] Param --detach will run container in background
If you want troubleshoot startup and see logs in the console directly, remove --detach parameter

Typical SDNext container will start in ~6sec and will be ready to accept connections on port 7860 Typical SD.Next container startup is around 6 seconds, then it is ready on port 7860.

Publish

If you want to share an image or deploy it on a cloud platform, publish it to a container registry.

There are many registries. Docker Hub is the most common.
Other options include GitHub Packages, AWS ECR, Azure ACR, Google AR, and Quay.

Example using Docker Hub

  1. Create an account on Docker Hub
  2. Create a personal access token in your Docker Hub account
  3. Login to Docker Hub from your terminal

    docker login --username --password

  4. Tag your local container with your Docker Hub username and repository name

    docker tag sdnext/sdnext-cuda /sdnext-cuda

  5. Push your container to Docker Hub

    docker push /sdnext-cuda

Your container is now available on Docker Hub and can be seen on
https://hub.docker.com/repository/docker/_username_/sdnext-cuda/!

Run Cloud

Once your container is published, run it on any cloud platform that supports Docker containers,
for example RunPod or AWS ECS.

Example using RunPod:

  1. Login to RunPod
  2. Create Pod
    1. Select platform with desired GPU
    2. Edit template:

      Container image: username/sdnext-cuda:latest
      Expose HTTP port: 7860

  3. Deploy Pod
    Wait for deployment to complete
  4. Connect to Pod
    RunPod will provide with a public hostname over which you can access your SD.Next instance

Extra

Additional Docker commands that may be useful:

Tip

Inspect image

docker image inspect sdnext/sdnext-cuda

Tip

Clean Up

docker image ls --all
docker image rm <id>
docker builder prune --force

Tip

List Containers

docker container ls --all
docker ps --all

Tip

View Log

docker container logs --follow <id>

Tip

Stop Container

docker container stop <id>

Tip

Test GPU

docker info  
docker run --name cudatest --rm --gpus all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark

Tip

Test Torch

docker pull pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime  
docker run --name pytorch --rm --gpus all -it pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime

Manual Install

Warning

URLs below are examples for Ubuntu 24 Check your Linux distribution and version and use appropriate packages instead

Docker

wget https://download.docker.com/linux/ubuntu/dists/oracular/pool/stable/amd64/containerd.io_1.7.25-1_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/oracular/pool/stable/amd64/docker-ce_27.5.1-1~ubuntu.24.10~oracular_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/oracular/pool/stable/amd64/docker-ce-cli_27.5.1-1~ubuntu.24.10~oracular_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/oracular/pool/stable/amd64/docker-buildx-plugin_0.20.0-1~ubuntu.24.10~oracular_amd64.deb
wget https://download.docker.com/linux/ubuntu/dists/oracular/pool/stable/amd64/docker-compose-plugin_2.32.4-1~ubuntu.24.10~oracular_amd64.deb
sudo dpkg -i *.deb

sudo groupadd docker
sudo usermod -aG docker $USER
systemctl status docker
systemctl status containerd

nVidia Container ToolKit

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --gpus all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark

© SD.Next - Check out Docs site

Clone this wiki locally