LivePortrait: portrait animation with stitching and retargeting control

What LivePortrait solves, and who it is actually for

LivePortrait animates a still portrait. You supply a source image and a driving signal, and the project produces a video in which the source face takes on the motion of the driver. The repository describes this as "Efficient Portrait Animation with Stitching and Retargeting Control", and the two named controls are the interesting part: stitching and retargeting. Retargeting means the driving motion can be transferred onto a source face with different proportions, and stitching refers to how separately generated regions are combined into one coherent frame.

The audience is not the casual user. There is a Hugging Face Space at KlingTeam/LivePortrait and a Windows one-click installer hosted on Hugging Face, so a non-programmer has a path in. But the repository itself is a PyTorch codebase with two separate inference scripts, a Gradio app, and a pretrained_weights directory you have to populate. If you are evaluating this for a product, you are evaluating a research implementation that was later adopted by video platforms, not a packaged SDK.

The mechanism: two inference paths and two model families

The repository layout tells you most of the architecture before you read any code. inference.py handles humans; inference_animals.py handles cats and dogs. app.py and app_animals.py are the corresponding Gradio interfaces. The 2024-08-02 update note announces the Animals model, and the 2025-01-01 note says a new Animals version was trained with more data. So the two model families are maintained on separate schedules, and an improvement to one does not imply anything about the other.

Dependencies are split across three requirement files. requirements.txt pulls in requirements_base.txt and then pins onnxruntime-gpu==1.18.0 and transformers==4.38.0. The presence of onnxruntime-gpu rather than plain onnxruntime means the default path expects an NVIDIA GPU. requirements_macOS.txt exists as a separate file, consistent with the 2024-07-17 update that added Apple Silicon support from a contributor pull request. The 2024-10-18 update bumped transformers and gradio specifically to close security vulnerabilities, which is the kind of change that matters if you pinned an older environment and never revisited it.

Two other scripts are worth noting. speed.py exists at the top level, so performance measurement is treated as a first-class concern rather than an afterthought. And the 2024-07-10 update mentions audio and video concatenating, driving video auto-cropping, and template making "to protect privacy", which suggests the intended workflow includes preparing driving material rather than feeding raw footage straight in.

Installing LivePortrait and running a first inference

The README's Getting Started section begins by telling you to clone the code, and the repository ships requirements.txt, requirements_base.txt and requirements_macOS.txt. The commands below follow that layout: clone, create an environment, install the base requirements, then the GPU extras. The README does not document a single canonical install command beyond this, so treat the file names as the source of truth.

git clone https://github.com/KlingAIResearch/LivePortrait.git
cd LivePortrait
python -m venv .venv
source .venv/bin/activate
pip install -r requirements_base.txt
pip install -r requirements.txt

requirements.txt starts with a line that includes requirements_base.txt, so installing both is redundant but harmless. The two pinned packages it adds are onnxruntime-gpu==1.18.0 and transformers==4.38.0. If pip resolves a different ONNX Runtime build on your machine, the GPU path in the inference scripts will not behave as the repository expects.

On macOS with Apple Silicon, the repository provides a separate file, consistent with the 2024-07-17 update. Use it instead of the GPU requirements.

pip install -r requirements_macOS.txt

Weights are not in the repository. The pretrained_weights directory is a top-level entry but the README's Getting Started section, as given, is cut off before it explains how those files are fetched. Check that directory before running anything, because both inference.py and inference_animals.py depend on it.

For an interactive first run, the Gradio apps are the entry points. app.py is the human model interface and app_animals.py is the animal one.

python app.py

According to the update notes, the Gradio interface gained pose editing for source portraits on 2024-07-24, precise portrait editing on 2024-08-06, and regional control plus image driven mode on 2024-08-19. Those four features are the ones to look for in the UI once it loads.

Where LivePortrait is the wrong tool

The licence is the first problem. The repository metadata reports NOASSERTION, which means GitHub could not classify the LICENSE file into a standard identifier. The README does not state terms in the excerpt available. Before you ship anything commercial, read LICENSE yourself; a research release from a company with commercial video products behind it is exactly the case where you should not assume permissive terms.

The second constraint is the Windows installer. The most recent one-click build the README points to is LivePortrait-Windows-v20240829, dated 2024-08-29, and it is hosted on Hugging Face rather than in the repository. The README also mentions that the installer supports auto-updates, but the auto-update mechanism is documented in the Hugging Face repository, not here. If your deployment plan depends on a maintained Windows binary, you are depending on a build that has not been refreshed in the repository's own update log since August 2024.

Third, this is an animation tool, not a face swap or identity transfer tool, and it is not a general video generation model. If your input is a video and your goal is to replace the person in it, you want a different class of system. LivePortrait takes a portrait and drives it. Feeding it a low-resolution or heavily occluded source will fail at the detection stage, and the 2024-07-24 note about lowering the default detection threshold to increase recall is a hint that detection is the fragile step in the pipeline.

Finally, the top-level update log's most recent entry is 2025-06-01, and the repository's last push was on 2026-06-01. That is a year of no logged feature changes with a push at the end. Do not read the push date as evidence of an active release cadence; the changelog is the better signal, and it shows the last documented feature work in January 2025.

LivePortrait compared with SadTalker

SadTalker is the comparison people search for, and the difference is in what drives the animation. SadTalker is built around audio-driven talking heads: you give it a portrait and a speech clip, and it produces a talking face. LivePortrait's primary path is visual driving, where a driving video supplies the motion. The repository's own framing is stitching and retargeting control, not speech synthesis.

The practical consequence is that LivePortrait gives you finer control over expression and pose because the motion comes from an actual performance rather than being inferred from phonemes. It also means you must supply that performance. The 2024-07-10 update about audio and video concatenating suggests LivePortrait can combine an audio track with generated video, but that is assembly, not lip-sync generation from audio alone.

There is also a ComfyUI angle. The 2024-08-06 update credits ComfyUI-AdvancedLivePortrait as the inspiration for the precise portrait editing feature in the Gradio interface, which means a node-based front end for this model exists outside the repository. If your team already works in ComfyUI, that is a real alternative to running app.py directly, and it is worth checking before you build tooling around the Gradio app.

Maintenance cost, licence risk and what to pin

The upgrade surface is small but sharp. Three requirement files, two pinned packages, and a set of pretrained weights that live outside version control. The 2024-10-18 update is the cautionary example: transformers and gradio were bumped to close security vulnerabilities. If you installed before that date and never re-checked, you were running the vulnerable versions. Pin the versions you install and schedule a re-read of requirements.txt rather than assuming the environment stays current.

The licence question deserves more than a glance. NOASSERTION means the classifier failed, not that the project is unlicensed and not that it is permissive. The README excerpt does not restate the terms. Read LICENSE in the repository root and decide from the text, not from the absence of a badge.

The weights are a separate question from the code. They are downloaded into pretrained_weights rather than committed, and the repository does not describe their terms in the excerpt available. If you are building a product, the code licence and the weight licence are two checks, not one.

Editorial conclusion

Adopt LivePortrait if you need a self-hosted portrait animation pipeline and you are willing to manage PyTorch, ONNX Runtime GPU and the pretrained weight downloads yourself. Skip it if you need an official Windows build you can trust for long-term use, or if your GPU stack cannot run onnxruntime-gpu 1.18.0. Before committing, read requirements.txt and requirements_macOS.txt, confirm your CUDA and ONNX Runtime versions line up, and decide whether the Windows one-click installer from 2024-08-29 is acceptable given that the repository has not published a newer official build.

Frequently asked questions

Official sources

1. Issues
2. KlingAIResearch/LivePortrait on GitHub
3. Project website
4. README