SadTalker Docker setup.
Get to your first video.

Run the commands on the Linux machine that has the NVIDIA GPU. If you rented a GPU server, connect to it over SSH first. Your Mac or Windows laptop can be the control computer; don’t run the setup in its local terminal by mistake.

• A Linux NVIDIA GPU host or VM. Our test used Ubuntu 22.04.5 and an RTX 4090.
• A working NVIDIA driver, Docker Engine, and NVIDIA Container Toolkit configured for Docker.
• Bash, curl and unzip, an internet connection, and an account allowed to run Docker.
• Free space for the image, models and temporary files. See the measured disk footprint before using a small server disk.

nvidia-smi
docker --version
docker info --format '{{json .Runtimes}}'
command -v bash curl unzip

You should see your GPU, a Docker version, nvidia in the runtime list, and paths for all three utilities. Fix a failed check before starting the kit. If curl or unzip is missing on Ubuntu, install it with sudo apt-get update && sudo apt-get install -y curl unzip.

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Use a fresh working folder for the first setup. The ZIP contains the tested scripts and Dockerfile; the image and model weights are fetched separately. If you already saved the ZIP on the server, skip the curl command and open the folder containing it.

Get the kit onto the GPU machine

mkdir -p ~/sadtalker-work
cd ~/sadtalker-work
curl -fL --retry 3 -o sadtalker-starter-kit.zip \
  https://sadtalker.ai/sadtalker-docker/sadtalker-starter-kit.zip
unzip sadtalker-starter-kit.zip
cd sadtalker-starter-kit
chmod +x setup.sh run.sh build.sh

The prompt should now be inside sadtalker-starter-kit. Use a folder path you can write to; the /root path in our screenshots is specific to the test server.

Let setup finish

./setup.sh

Setup pulls the fixed image if needed, checks a real GPU calculation, fetches missing models, and prepares a demo portrait and audio clip. The first run takes longer; keep the terminal open until you see:

GPU OK: NVIDIA GeForce RTX 4090
… model checks …
Setup complete. Run: ./run.sh inputs/demo.png inputs/demo.wav

Your GPU name may differ. If setup stops with an error, use the matching fix below, then run ./setup.sh again in this same folder.

Generate the bundled demo

./run.sh inputs/demo.png inputs/demo.wav

Wait for Output video(s): and the MP4 path. That is your finished file. The progress bars alone don’t mean the whole run has finished.

Copy a clear portrait to inputs/portrait.png and your voice recording to inputs/speech.wav. Start with a short clip and one clearly visible face so you can check the result before a longer run.

./run.sh inputs/portrait.png inputs/speech.wav

PNG and JPG/JPEG images are accepted. Audio can be WAV, MP3, M4A, FLAC or OGG. Keep the file’s real extension; renaming an MP3 to WAV does not convert it. Put quotes around paths containing spaces:

./run.sh "inputs/my portrait.jpg" "inputs/my voice.mp3"

The launcher always uses 512 + crop + still + GFPGAN. It accepts two file paths, not extra inference flags. It creates a separate input copy and output folder for each job. On later sessions, return to the same kit folder and run the launcher; there is no need to repeat setup unless something is missing.

scp -P SSH_PORT ./portrait.png ./speech.wav USER@HOST:REMOTE_KIT_PATH/inputs/

The terminal’s last path points to a file under outputs/<run-id>/. On a Linux desktop, open that file in your video player. On a remote server, copy it to your laptop to play it.

find "$PWD/outputs" -type f -name '*.mp4'

To retrieve one from a server, run this on your laptop. Replace REMOTE_MP4_PATH with the full path printed by the launcher, as well as the connection placeholders:

scp -P SSH_PORT USER@HOST:REMOTE_MP4_PATH ./sadtalker-result.mp4

SadTalker may print an internal results/… path during processing. The launcher’s final outputs/… path is the location on your machine. The 512 setting selects the model size; it is not a promise that the enhanced MP4 will be exactly 512 × 512.

If you rented the GPU, save your videos and anything you want to keep before ending the rental. Closing SSH does not stop server billing.

The launcher mounts ordinary folders from the kit into the container. These are bind mounts, so models and finished videos remain on the host after the temporary container exits.

How much disk space does it use?

Our test notes report 6.76 GB for the Docker image, 1.7G for checkpoints and 703M for GFPGAN weights. Docker and du report sizes differently, so treat these as measured components, not an exact total or a minimum disk specification.

Leave additional room for image extraction, partial files, the operating system, and your videos. A source build needs more room again. Check both the Docker disk and the kit folder if they are on different drives:

docker system df
printf 'Docker storage: '
docker info --format '{{.DockerRootDir}}'
df -h .
du -sh checkpoints gfpgan/weights outputs logs

Keep using the same folder to reuse weights. Extracting another kit elsewhere creates a separate model store. --rm removes the run’s temporary container, not these host folders. Avoid deleting the kit or pruning Docker storage just to retry a failed run.

Read the last error before trying again. These checks address the script’s failure messages and common host problems; they are not a claim that every failure below was reproduced on the test server.

Each generation writes a log to logs/<run-id>.log, including failed runs. Open the log path shown when the launcher starts. It helps identify whether the problem happened while reading inputs, loading a model, generating frames or enhancing the face.

This Docker release is tested for the command line. The kit does not start a browser interface, expose a port, or create a Gradio link. Running ./run.sh produces an MP4 directly.

A Docker WebUI launch has not been verified with this image, so there is no tested WebUI command in this guide yet. If you want a browser interface now, use the separate Windows WebUI guide or GitHub setup guide. Those are different installation routes.

Windows Docker/WSL and macOS GPU execution are also outside this kit’s tested scope. You can still use either computer to connect to the tested Linux GPU host over SSH.

Test date

25 September 2026

Host

Ubuntu 22.04.5 · NVIDIA RTX 4090

Driver / Docker

580.95.05 / 28.1.1

PyTorch

2.0.1+cu118

SadTalker source

cd4c046

Demo settings

512 · crop · still · GFPGAN

The updated setup and generation scripts passed using the published image reference. The final demo took 68.588 seconds. An earlier enhanced demo was played and approved during testing. These are results for this short clip on this machine, not a speed guarantee.

A clean-machine installation has not been tested. The anonymous pull used cached layers, and the final setup reused existing models. First-time transfers and a completely fresh host remain outside that evidence.

Use the same image

The readable version is sonukumar28/sadtalker:1.0.0. The scripts use the digest below so they request the exact tested image, even if a tag later changes.

sonukumar28/sadtalker@sha256:ec420a506684e2e26964a39ede490a654d77c025fcc90408ce2b3187bf5703ee

This starter kit is an independent wrapper for OpenTalker’s SadTalker, not an official upstream release. The image includes upstream source and its license; weights come separately from upstream sources.

Image on Docker Hub · Read the final test record

You can skip this section for normal use. The ZIP includes the Dockerfile and build script for people who want to inspect or customize the image. Install Git first, then run these commands inside the kit folder:

./build.sh
SADTALKER_IMAGE=sadtalker:test ./setup.sh
SADTALKER_IMAGE=sadtalker:test ./run.sh inputs/demo.png inputs/demo.wav

The build checks out source revision cd4c046 and refuses to overwrite an existing build-source folder. Some dependencies are pinned, but the base image and all transitive dependencies are not fully locked. A fresh build may differ from the published image. Use the same SADTALKER_IMAGE setting for setup and generation.