SadTalker GitHub Guide: Setup, RTX 4090 Benchmarks & Fixes
Everything the official GitHub README leaves out: complete architecture breakdown, step-by-step cross-platform installations for Ubuntu, Windows, and macOS, real nvtop GPU activity recordings, and verified fixes for undocumented TorchVision and Gradio errors.
Official Repository Details
Verified GitHub source, release status, and distinction between official and fork repos.
Repository Identity
The primary upstream repository is maintained by OpenTalker (originating from Xi'an Jiaotong University and Tencent AI Lab). While older tutorials refer to Winfredy/SadTalker, OpenTalker is the current authoritative upstream.
Key Project Milestones
- 512x512px Beta Model: High-definition face texture synthesis released in v0.0.2.
- Watermark Removed: The default diagnostic watermark was permanently retired in subsequent releases.
- Full-Image Mode: Added
--preprocess fullto animate portraits without cropping.
Commercial License Clarity
The code itself is published under the permissive Apache 2.0 License. However, the pretrained 3DMM and landmark extraction checkpoints incorporate non-commercial research models (such as BFM and GFPGAN). For commercial deployment, weights must be retrained on open-domain datasets.
SadTalker Folder Structure Explained
Understanding what each directory does saves hours of troubleshooting when locating model weights, customizing output paths, or inspecting rendering pipelines.
What Every Folder Does
Stores pre-trained model weights including SadTalker_V0.0.2_256.safetensors, SadTalker_V0.0.2_512.safetensors, and 3DMM coefficients. Populated via scripts/download_models.sh.
Contains the offline face restoration models (GFPGANv1.4.pth and parsing models) for sharp skin pores, natural teeth, and pupil clarity.
Core deep learning algorithms: audio2exp (mel-spectrogram to expression), audio2pose (head nod/tilt), and facerender (PyTorch neural renderer).
Default output destination organized by timestamp folders (e.g., ./results/2026_09_12_08.59.12/). Contains both raw generated mp4 and enhanced mp4 files.
Sample speech audio files (driven_audio/*.wav) and reference portrait test photos (source_image/*.png).
Which File Should Beginners Run?
Spawns a local Gradio browser interface on http://127.0.0.1:7860. Features drag-and-drop image and audio inputs, slider-based expression settings, and instant video preview.
The headless CLI engine. Ideal for automated cloud servers, batch pipelines, Vast.ai and RunPod instances, and fine-tuning generation arguments without browser overhead.
Automated bootstrapping scripts. On Windows, double-clicking webui.bat creates a virtual environment, installs PyTorch, pulls checkpoints, and launches Gradio automatically.
inference.py with --size 512 --still --enhancer gfpgan to maximize facial fidelity and prevent neck jitter.NVIDIA GeForce RTX 4090: nvtop & Speed Test
We benchmarked SadTalker on a dedicated 24GB RTX 4090 system executing complete 3D facial modeling, landmark tracking, neural rendering, and GFPGAN face restoration. Watch the real-time nvtop capture below.
nvtop monitoring demonstrates GPU compute spikes during 3DMM extraction and steady 40-70% tensor core utilization while GFPGAN processes 281 frames at 10.60 it/s.Inference Execution Times
Real: 40.490s
nvidia-smi terminal output confirming RTX 4090 24,564 MiB VRAM and driver 570.172.08
Vast.ai cloud instance specification details and benchmark performance rating
Inference execution showing 3DMM extraction, 18.48 it/s face renderer, and 10.60 it/s GFPGAN enhancement
Hardware Requirements: VRAM, Disk & Compute
SadTalker requires significant VRAM when running 512px resolution with the GFPGAN enhancer. Here is what your hardware needs:
| Component | Minimum (256px) | Recommended (512px) | Production / Cloud Rig |
|---|---|---|---|
| GPU VRAM | 4 GB (GTX 1660 / RTX 3050) | 8 GB - 12 GB (RTX 3060 / 4070) | 16 GB - 24 GB (RTX 4090 / A100) |
| CUDA Version | CUDA 11.3+ | CUDA 11.8 - 12.4 | CUDA 12.4 - 12.8 |
| System RAM | 8 GB | 16 GB - 32 GB | 32 GB - 64 GB |
| Disk Storage | 12 GB free space | 25 GB SSD space | 50 GB NVMe |
| Inference Latency | ~2.5 to 4 minutes | ~60 to 90 seconds | 40.49 seconds |
Complete Cross-Platform Installation
Select your target operating system below for tailored terminal commands, prerequisite checks, and real screenshot evidence from verified environments.
Update Ubuntu & Install Critical Prerequisites
SadTalker depends on FFmpeg for combining the generated video frames with the driven audio wav file. Missing FFmpeg causes unhandled Python subprocess errors during audio muxing.
apt update && apt install -y git ffmpeg wget python3-pip
Live output of apt update and dependency installations
Clone Repository & Create Isolated Python 3.8 Conda Environment
The official repository is optimized for Python 3.8. Using Python 3.11 or 3.12 triggers wheel compilation failures for older PyTorch dependencies and facial landmark libraries.
# Clone official repo
git clone https://github.com/OpenTalker/SadTalker.git
cd SadTalker
# Create and activate Python 3.8 environment
conda create -n sadtalker python=3.8 -y
conda activate sadtalkerconda install -c conda-forge ffmpeg -yInstall PyTorch & Repository Requirements
Install PyTorch with CUDA acceleration before running the main requirements file.
# Install PyTorch with CUDA support
pip install torch torchvision torchaudio
# Install repository requirements
pip install -r requirements.txt
PyTorch CUDA Wheel Installation
Requirements Installation
Acquire Pretrained Weights & Checkpoints
SadTalker provides a dedicated bash script to fetch the essential checkpoints into checkpoints/ and gfpgan/weights/.
bash scripts/download_models.sh
Model Weights Fetched Automatically
Launch: Local Gradio WebUI or Headless CLI
Choose whether to interact via the web browser or execute batch jobs directly from the terminal.
Option A: Launch WebUI (Port 7860)
python app_sadtalker.py
Gradio local web server initialization
Active Gradio URL and live demonstration interface link
SadTalker Gradio WebUI running locally with source image and audio inputs
Option B: Headless CLI Inference
time python inference.py \
--driven_audio ./examples/driven_audio/bus_chinese.wav \
--source_image ./examples/source_image/full_body_1.png \
--result_dir ./results \
--enhancer gfpgan
CLI inference execution with driven audio and source image
Terminal output with detailed stage execution timings
Fixes for Undocumented GitHub Errors
When installing SadTalker on modern operating systems or recent PyTorch environments, users frequently encounter unmaintained third-party library breakages. Here are the verified single-line command fixes:
1. ModuleNotFoundError: No module named 'torchvision.transforms.functional_tensor'
Common BugCause: In newer releases of torchvision, the internal module functional_tensor was deprecated and unified into torchvision.transforms.functional. The basicsr dependency still imports the legacy path.
sed -i 's/from torchvision.transforms.functional_tensor import rgb_to_grayscale/from torchvision.transforms.functional import rgb_to_grayscale/' $(python -c "import site; print(site.getsitepackages()[0])")/basicsr/data/degradations.py2. AttributeError: 'Row' object has no attribute 'style'
Gradio MismatchCause: Running python app_sadtalker.py with modern Gradio 4.x fails because Gradio removed the .style() method.
pip install "gradio==3.41.2"3. ModuleNotFoundError: No module named 'TTS'
Optional Voice FeatureCause: Coqui TTS is optional for the voice cloning tab in the Gradio WebUI. If you need voice synthesis directly inside the demo, install Coqui TTS:
pip install TTS==0.13.34. Missing FFmpeg Subprocess / Audio Not Synced
Muxing ErrorCause: Python generates the raw video frames successfully, but fails at the final step when combining the audio track because FFmpeg is absent in the Conda environment binary PATH.
conda install -c conda-forge ffmpeg -yProduction CLI Flags & Parameter Guide
Essential command-line arguments to eliminate head wobbling, restore sharp skin details, and render full body portraits.
Stabilizes Head & Shoulders: Essential for professional presenters, e-learning instructors, and corporate narrators. It locks global neck rotations so the portrait remains steady while only the mouth and subtle facial expressions animate.
Cropping Mode: crop zooms into the face for maximal detail; resize keeps the portrait frame; full animates the face seamlessly within the full original source picture.
Facial Super-Resolution: Passes the generated frames through GFPGAN v1.4 to restore crisp eyelashes, clear pupils, teeth definition, and high-frequency skin textures.
Model Resolution: 256 provides fast rendering with low VRAM; 512 activates the high-definition face model released in v0.0.2.
Recommended Production Command:
python inference.py \
--driven_audio ./narration.wav \
--source_image ./presenter.png \
--result_dir ./results \
--size 512 \
--still \
--preprocess crop \
--enhancer gfpganSetup Cheatsheets & Automation Notebooks
Get ready-to-run automation files tested on modern NVIDIA GPUs. Upload to Vast.ai, Colab, or execute on your local workstation.
Jupyter Execution Notebook
Ready-to-upload notebook for JupyterLab, Vast.ai, or Google Colab. Includes GPU verification, automated bug patches, and timing benchmarks.
Automated Shell Setup Script
Automated bash script for Ubuntu and Linux. Checks system FFmpeg, creates conda env, installs dependencies, patches basicsr, and fetches models.
Frequently Asked Questions (GitHub & Local Setup)
Straightforward answers to the most common questions across the SadTalker GitHub issue tracker.