QWE AI Academy You want a static portrait to lip-sync to an audio clip. Locally. For free. That’s what SadTalker does – and it’s still one of the best open-source options for talking head AI, three years after its CVPR 2023 paper dropped. But installing it in 2026 is trickier than most tutorials admit, because most tutorials were written in 2023 and haven’t been updated since.
This guide covers SadTalker v0.0.2 rc – the current (and only tagged) release – with the commands that actually work today, plus the failure modes buried in GitHub issues.
What you’re actually installing
SadTalker generates 3D motion coefficients (head pose + expression) from audio, then feeds them to a 3D-aware face renderer. The research behind it landed at CVPR 2023 – full paper at arXiv:2211.12194. It’s Apache 2.0 licensed, runs completely offline, and is not an official Tencent product despite the authorship overlap.
Reality check before you start: the latest release is SadTalker v0.0.2 rc, published June 5, 2023 (per the GitHub Releases page). As of mid-2026, there hasn’t been another tagged release. The last dated changelog entry on the README is from June 12, 2023. The project isn’t dead – pull requests still land – but you’re installing a three-year-old release candidate, and that shapes everything below.
System requirements
Official docs don’t publish a strict requirements table, so here’s what works based on the install.md and community reports:
| Component | Minimum | Recommended |
|---|---|---|
| OS | Windows 10, Ubuntu 20.04, macOS 12 | Ubuntu 22.04 or Windows 11 |
| Python | 3.8 | 3.8 or 3.10 (avoid 3.11+) |
| GPU | None – CPU works but is slow | NVIDIA with ≥6GB VRAM, CUDA 11.7-12.1 (per community reports) |
| RAM | 8GB | 16GB+ |
| Disk | ~5GB (repo + models) | 10GB free |
| Extras | Git, FFmpeg in PATH | Conda for env isolation |
Two warnings before you buy hardware to run this. SadTalker works fine in CPU mode, but GPU mode is currently impossible on NVIDIA RTX 50xx (Blackwell) GPUs – more on that in the errors section. And on CPU, generating a 30-second clip typically takes 10-30 minutes (per community reports), so a GPU is close to mandatory for anything beyond a one-off proof of concept.
Get the source (from the right repo)
Every second tutorial online still tells you to git clone https://github.com/Winfredy/SadTalker.git. That’s the old URL. The maintained repository is OpenTalker/SadTalker – confirmed in the official install.md. Cloning the wrong one means outdated code and broken model paths.
git clone https://github.com/OpenTalker/SadTalker.git
cd SadTalkerWatch out: If a guide tells you to clone Winfredy/SadTalker.git, close the tab. It’s almost certainly a 2023 article that hasn’t been touched. The domain name of the source doesn’t matter – the clone URL does.
Install SadTalker v0.0.2 step by step
Use conda. Yes, venv works too, but the official install.md uses conda and there’s no reason to fight the tooling the maintainers actually test against.
- Create the environment with Python 3.8:
conda create -n sadtalker python=3.8 && conda activate sadtalker - Install PyTorch 2.0 (per current install.md – not the old 1.12.1+cu113 command from the 2023 README):
pip install torch torchvision torchaudio - Install FFmpeg into the environment:
conda install ffmpeg - Install the remaining Python deps:
pip install -r requirements.txt - Download the model checkpoints:
bash scripts/download_models.shon Linux/macOS. On Windows, download from the GitHub Releases page and unzip into./checkpoints.
One quiet win from v0.0.2 rc: checkpoint packages went from 7GB down to 1GB after being repackaged as safetensors (per the official release notes). If you followed an old guide expecting a multi-hour download, it’ll be over before you refill your coffee.
First run and verification
Skip the WebUI for the first test – use the inference script. It fails louder, which is what you want when debugging.
python inference.py
--driven_audio examples/driven_audio/bus_chinese.wav
--source_image examples/source_image/full_body_1.png
--enhancer gfpgan
--preprocess full
--stillPer the official README, results save to results/$SOME_TIMESTAMP/*.mp4. Open the file. If it plays and the mouth roughly matches the audio, the install works. Now launch the WebUI:
python app_sadtalker.py
# or on Linux/macOS:
bash webui.shPoint your browser at http://127.0.0.1:7860. If Gradio loads but generated videos won’t play back in the browser, don’t blame the model – it’s almost always the Gradio version. Downgrade: pip install gradio==3.50.0. That single pin resolves the silent playback bug for most users, per the sadtalker.ai FAQ.
A quick pause before the errors
Here’s something worth sitting with: SadTalker is an unmaintained research release that’s three years old, and it’s still one of the better free options for local talking-head generation. What does that say about the state of open-source AI video? A lot of newer projects in this space launched with more fanfare but shipped less usable code. Sometimes the boring, quiet repo that stopped getting commits is the one that actually works – because the fundamentals were solid enough not to need constant patching. Whether that holds another three years from now is genuinely unclear.
The errors you’ll actually hit
These come from GitHub issues – not hypothetical, not from a changelog. Real error messages, real fixes.
1. ERROR: Could not find a version that satisfies the requirement torch==1.12.1+cu113
You followed an old tutorial with the outdated PyTorch pin on Python 3.11. Those wheels were never built for 3.11+. GitHub issue #926 documents this exact error on Python 3.11.9 – the wheels simply don’t exist for that Python version. Fix: create a Python 3.8 or 3.10 env, or use the modern pip install torch torchvision torchaudio command instead.
2. torch.cuda.OutOfMemoryError: CUDA out of memory
This hits at the Face Renderer step, usually after audio2exp completes. Reported repeatedly in issues #130, #196, and #234. Fix: drop --size 512 to --size 256, remove --enhancer gfpgan (GFPGAN is a VRAM hog), or reduce batch size in the WebUI. If you’re running SadTalker as a Stable Diffusion WebUI extension alongside SD itself, restart the WebUI so the SD checkpoint releases VRAM first.
3. RuntimeError: Attempting to deserialize object on a CUDA device but torch.cuda.is_available() is False
Reported in community threads for macOS and AMD GPU setups. The model weights were saved with a CUDA tensor map; loading on MPS/CPU trips this. Fix: install the CPU or MPS build of PyTorch for your platform, and confirm torch.cuda.is_available() returns False intentionally so the code path uses map_location='cpu'.
4. RTX 50xx (Blackwell) GPUs don’t work in GPU mode.
This is the one nobody mentions. The issue: torchvision C++ ops that SadTalker depends on are not present in the PyTorch builds compatible with CUDA 12.8, which is what Blackwell cards require. GitHub issue #1023 (filed December 2025) documents this in detail – see issue #1023 for current status. If you just bought a 5080 or 5090 machine expecting to run SadTalker, your options right now are CPU mode or waiting for a compatibility patch.
Upgrading and uninstalling
There’s no upgrade path in the traditional sense. Since v0.0.2 rc is still the latest tagged release (as of mid-2026), git pull inside your SadTalker folder is the closest thing – it grabs whatever unreleased commits have landed on main. Do that in a copy of the folder first if your current install works, because unpinned dependency changes can break a working setup.
To uninstall cleanly: conda remove -n sadtalker --all nukes the environment, and rm -rf SadTalker (or delete the folder in Explorer) removes the repo and checkpoints. No system-wide state, no registry keys, no services – it’s a self-contained folder plus a conda env.
FAQ
Is there a newer version than v0.0.2 rc?
No. As of July 2026, v0.0.2 rc from June 2023 is still the latest tagged release on GitHub.
Can I run SadTalker without a GPU?
Yes – but 10-30 minutes per 30-second video. Fine for a single test. A non-starter for anything you’d call a workflow. Cloud GPU rental (via services like RunPod or Vast.ai) is an option for batch work, though you’ll need to re-upload model weights each session unless you pay for persistent storage.
Why does my install pass but the generated video has no lip movement?
Usually the audio file. SadTalker expects clean vocal audio – per community practice, 16kHz mono WAV is most reliable. Background music, noise, or very quiet speech gives you a face that stares rather than talks. A few people have had success preprocessing audio through Audacity (normalize, high-pass filter), but the bigger fix is usually just isolating the voice track first. Also check your source image: front-facing, neutral expression, and decent resolution (per community reports, at least 512×512 tends to work best) gives SadTalker the clearest signal to work with.
Next step: run the inference command above with your own portrait and audio clip. That first successful output – even if imperfect – tells you your environment is solid and you can tune from there.