liveportrait: portrait animation with retargeting control

Bring portraits to life with a source image and a chosen motion direction.

• 2025/06/01: 🌍 Over the past year, LivePortrait has become an efficient portrait-animation solution for humans, cats, and dogs, used across video platforms, creative tools, and research workflows.
• 2025/01/01: 🐶 We updated the Animals model with additional training data and refreshed example assets. Details are available here.
• 2024/10/18: ❗ Dependency versions were updated to improve installation safety and consistency. See the change notes.
• 2024/08/29: 📦 The Windows package was refreshed with a simpler setup path and update support.
• 2024/08/19: 🖼️ Image-driven mode and regional control are now supported for more precise portrait direction.
• 2024/08/06: 🎨 Precise portrait editing was added to the interface for more detailed expression control.
• 2024/08/05: 📦 Windows users can access the one-click package for both Humans mode and Animals mode.
• 2024/08/02: 😸 A new Animals model arrived with several additional improvements.
• 2024/07/25: 📦 The downloadable package now includes a direct run path for Windows users.
• 2024/07/24: 🎨 Pose editing for source portraits was added, with a lower default detection threshold.
• 2024/07/19: ✨ Portrait video editing, also known as v2v, is supported for compatible workflows.
• 2024/07/17: 🍎 Apple Silicon support was added for the Humans workflow.
• 2024/07/10: 💪 Audio and video concatenation, driving-video auto-cropping, and motion-template creation are supported.
• 2024/07/09: 🤗 An online demo was released for trying the workflow without local setup.
• 2024/07/04: 😊 The initial inference code and models were released for research and experimentation.
• 2024/07/04: 🔥 The project homepage and technical report were released together with the first public implementation.

This repository, named LivePortrait, contains an official PyTorch implementation for efficient portrait animation with stitching and retargeting control. The workflow turns a source portrait into expressive motion while keeping the original identity and visual structure coherent.

LivePortrait is actively improved for research, creative exploration, and practical image-to-video experiments. If you find an issue or have a suggestion, use the project workflow to share it.

git clone https://github.com/KlingTeam/LivePortrait
cd LivePortrait

# create env using conda
conda create -n LivePortrait python=3.10
conda activate LivePortrait

For Linux 🐧 or Windows 🪟 Users

The X-Pose dependency is required by Animals mode. Checking the CUDA version is optional if you only want to run Humans mode.

nvcc -V  # example versions: 11.1, 11.8, 12.1, etc.

# for CUDA 11.1
pip install torch==1.10.1+cu111 torchvision==0.11.2 torchaudio==0.10.1 -f https://download.pytorch.org/whl/cu111/torch_stable.html

# for CUDA 11.8
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu118

# for CUDA 12.1
pip install torch==2.3.0 torchvision==0.18.0 torchaudio==2.3.0 --index-url https://download.pytorch.org/whl/cu121

Finally, install the remaining dependencies:

pip install -r requirements.txt

For macOS  with Apple Silicon Users

The X-Pose dependency does not support macOS, so it can be skipped. Humans mode works as usual, while Animals mode is not supported on this platform.

# for macOS with Apple Silicon users
pip install -r requirements_macOS.txt

The easiest way to download pretrained weights is with the Hugging Face command-line client:

# !pip install -U "huggingface_hub[cli]"
huggingface-cli download KlingTeam/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"

If the main mirror is unavailable, use the alternate endpoint:

# !pip install -U "huggingface_hub[cli]"
export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli download KlingTeam/LivePortrait --local-dir pretrained_weights --exclude "*.git*" "README.md" "docs"

Alternatively, download the complete weights package from the linked project resources and place the unzipped files in ./pretrained_weights.

Make sure the directory structure matches the expected layout before starting inference.

Fast hands-on (humans) 👤

# For Linux and Windows users
python inference.py

# For macOS users with Apple Silicon
PYTORCH_ENABLE_MPS_FALLBACK=1 python inference.py

A successful run produces an output video named animations/s6--d0_concat.mp4. It combines the driving video, source image or video, and generated result.

You can change the input by specifying the source and driving arguments:

# source input is an image
python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d0.mp4

# source input is a video
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d0.mp4

# more options
python inference.py -h

Fast hands-on (animals) 🐱🐶

Animals mode is tested on Linux and Windows with an NVIDIA GPU.

Build the MultiScaleDeformableAttention operation first, then run the animal inference script:

cd src/utils/dependencies/XPose/models/UniPose/ops
python setup.py build install
cd -

python inference_animals.py -s assets/examples/source/s39.jpg -d assets/examples/driving/wink.pkl --driving_multiplier 1.75 --no_flag_stitching

A successful run produces animations/s39--wink_concat.mp4.

Driving video auto-cropping 📢📢📢

Below is an auto-cropping example:

python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d13.mp4 --flag_crop_driving_video

Adjust --scale_crop_driving_video and --vy_ratio_crop_driving_video when the automatic crop needs refinement.

Motion template making

Auto-generated motion templates ending with .pkl can speed up inference and help protect source-video privacy:

python inference.py -s assets/examples/source/s9.jpg -d assets/examples/driving/d5.pkl  # portrait animation
python inference.py -s assets/examples/source/s13.mp4 -d assets/examples/driving/d5.pkl  # portrait video editing

The project includes a Gradio interface for a more approachable workflow:

# For Linux and Windows users
python app.py

# For macOS with Apple Silicon
PYTORCH_ENABLE_MPS_FALLBACK=1 python app.py

Animals mode has a separate interface and is tested on Linux with an NVIDIA GPU:

python app_animals.py

You can specify --server_port, --share, and --server_name as needed.

The optional --flag_do_torch_compile mode can make later inferences faster after its initial optimization step:

# enable torch.compile for faster inference
python app.py --flag_do_torch_compile

Note: torch.compile is not supported on Windows and macOS.

Or, try the online workflow through LivePortrait 🤗

Use the speed script to evaluate the inference time of each module:

# For NVIDIA GPU
python speed.py

The measurement notes are available in the project resources.

Discover tools and learning resources contributed by the LivePortrait community.

Community-developed Projects

Playgrounds, 🤗 HuggingFace Spaces and Others

• FacePoke Space
• Expression Editor Space
• Expression Editor Replicate
• Face Control Realtime Demo on FAL
• Replicate Playground
• Nuke can use LivePortrait through a community node; details are available here.
• LivePortrait is also available through Poe.

Video Tutorials

• Workflow of LivePortrait Video to Video by @curiousrefuge
• Google Colab tutorial by @Planet Ai
• Paper reading by @TwoMinutePapers
• ComfyUI Advanced LivePortrait by TutoView
• LivePortrait exploration and A deep dive into LivePortrait by TheoreticallyMedia
• LivePortrait hands-on tutorial by @AI Search
• ComfyUI tutorial by @Sebastian Kamph
• A tutorial on BiliBili

And so many thoughtful contributions from the community continue to expand the LivePortrait ecosystem 💖

We thank the contributors to FOMM, Open Facevid2vid, SPADE, InsightFace, X-Pose, and the wider open research community for their work and contributions.

Portrait animation technologies carry social risks, including potential misuse in creating deceptive media. Use the workflow responsibly, obtain permission for source images, and clearly identify synthetic or edited results where appropriate. Current synthesized results can contain visual artifacts that may help with detection. The project does not assume legal responsibility for generated outputs.

If LivePortrait is useful for your project or research, cite the work using the following BibTeX:

@article{liveportrait2024,
  title   = {LivePortrait: Efficient Portrait Animation with Stitching and Retargeting Control},
  author  = {LivePortrait Research Team},
  journal = {arXiv preprint},
  year    = {2024}
}

Long live open research.

LivePortrait Research; questions and collaboration requests can begin through the project workflow.