Guide · Open source

How to use first-order-model: install, run the demo and animate images

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

first-order-model is the open-source source code for the NeurIPS 2019 paper First Order Motion Model for Image Animation. You give it one still source image and a driving video, and it produces a video in which the still image moves the way the driving video moves. This guide walks through installing the dependencies, running the demo, the Docker route, and the cropping rules you need to follow, so you can produce your first animation.

First Order Motion ModelAliaksandrSiarohin/first-order-model · ★ 15k · MIT Install options & downloads

Quick start

1Clone the repository. Download the first-order-model source code and move into its folder.
2Install dependencies. Run pip install -r requirements.txt with Python 3.
3Download a checkpoint. Get a pretrained checkpoint from the Google Drive or Yandex Disk links in the README.
4Crop your inputs. Crop the driving video and source image, optionally using crop-video.py for suggestions.
5Run demo.py. Pass your config, driving video, source image and checkpoint, with --relative and --adapt_scale.
6Find the result. Open result.mp4 in the project folder to see the animated output.

Check whether this project fits your goal

The README describes research code, not a polished consumer app. It is aimed at researchers reproducing the paper, developers experimenting with keypoint-based image animation, and students learning how motion transfer works.

Training is referenced with multi-GPU setups on Titan-X cards, so plan for a GPU if you want to train. The README says the method can be modified for face-swap, but points to a separate project for that.

Good fit: reproducing the paper, building on the method, learning the technique.
Poor fit: a ready-made app for casual users, or face-swap out of the box.

Install the dependencies

The project supports Python 3. Clone the repository, move into its folder, and install the dependencies listed in requirements.txt with pip.

The README links pretrained checkpoints from Google Drive and Yandex Disk. You will need to download one before running the demo.

Prerequisites: Python 3 and pip.
Download a pretrained checkpoint from the links in the README.

pip install -r requirements.txt

Prepare your source image and driving video

The README states that driving videos and source images should be cropped before use. It provides crop-video.py as a semi-automatic helper: running it on a video generates ffmpeg crop commands. That script needs the face-alignment library, which the README says to install from its own repository.

For relative animation, the object in the first frame of the video and in the source image should have the same pose. Otherwise the README says results may suffer.

Crop both the driving video and the source image.
Use crop-video.py --inp to get crop suggestions.
Install face-alignment first if you use that script.

python crop-video.py --inp some_youtube_video.mp4

Run the animation demo

Run demo.py with your config file, driving video, source image and checkpoint. The README shows the --relative and --adapt_scale flags. The result is stored in result.mp4.

Replace dataset_name.yaml with the config for your dataset, such as config/vox-256.yaml as used in the Docker example.

--config: the YAML file for your dataset.
--driving_video: path to the driving video.
--source_image: path to the source image.
--checkpoint: path to the downloaded checkpoint.
--relative and --adapt_scale: the flags the README uses in its demo command.

python demo.py  --config config/dataset_name.yaml --driving_video path/to/driving --source_image path/to/source --checkpoint path/to/checkpoint --relative --adapt_scale

Optional: run the demo in Docker on Linux

If you have library compatibility problems and run Linux, the README suggests a Docker container for a more controlled environment. It requires Docker 19.03+ and nvidia-docker, and the nvidia-docker usage tests must pass. Build the image first from the project folder, then run the demo inside it with GPU access.

The Docker run command mounts your folder into /app and writes output to the file you name with --result_video.

Requirements: Docker 19.03+ and nvidia-docker.
The Docker route is optional; the README presents it as a fallback for compatibility issues.

docker build -t first-order-model .

docker run -it --rm --gpus all -v $HOME/first-order-model:/app first-order-model python3 demo.py --config config/vox-256.yaml --driving_video driving.mp4 --source_image source.png --checkpoint vox-cpk.pth.tar --result_video result.mp4 --relative --adapt_scale

Choose relative or absolute animation

The README describes two modes. Absolute animation uses the driving video's absolute keypoint positions with the source image's appearance. It has no special requirements on the inputs, but the README says it usually performs poorly because irrelevant details such as shape get transferred.

Relative animation estimates each keypoint's movement in the driving video and adds it to the source image's keypoint positions. The README says this usually performs better, but needs matching poses in the first frame.

Absolute: no pose requirement, usually weaker results.
Relative: usually better results, needs matching starting pose.

What people use it for

Animate a still portrait using the motion of a short driving clip, as in the README's VoxCeleb example.
Test relative versus absolute keypoint animation on the same inputs to compare results.
Reproduce the README's fashion or MGIF examples as a research exercise.
Learn how keypoint-based motion transfer works by reading the code and config files.

Frequently asked questions

Is first-order-model free to use?

The repository is released under the MIT licence, as shown in the project information. Check the LICENSE file in the repo for the full terms before you reuse the code.

What do I need to run first-order-model?

The README lists Python 3 and pip for the standard route, and Docker 19.03+ with nvidia-docker if you use the Docker route. It also says training was set up on multi-GPU Titan-X cards, so a GPU is strongly implied for training.

Why does my driving video need cropping?

The README states that driving videos and source images should be cropped before they can be used by the method. The crop-video.py script can suggest ffmpeg crop commands to help.

Can I use first-order-model for face-swap?

The README says the method can be modified for face-swap using supervised segmentation masks, but it is not out of the box. It points to a separate project, Motion Co-Segmentation, for unsupervised and supervised editing such as face-swap.

What is the difference between relative and absolute animation?

Absolute animation uses the driving video's absolute keypoint positions and has no pose requirement, but usually performs poorly. Relative animation adds the driving motion to the source keypoints and usually performs better, provided the starting poses match.

Is there an alternative to running first-order-model locally?

The README links a Colab and Kaggle notebook (demo.ipynb) with a GUI demo prepared by a contributor. Comparable projects named in the directory include articulated-animation, Thin-Plate-Spline-Motion-Model and LivePortrait.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use first-order-model if you are a researcher, developer or student who wants to reproduce or build on the NeurIPS 2019 keypoint-based image animation method and can handle cropping and command-line setup. If you want a polished app, a face-swap tool out of the box, or a no-GPU workflow, pick a different project such as LivePortrait or Thin-Plate-Spline-Motion-Model, or the authors' own articulated-animation for articulated objects.

Install options & downloads