Installation¶

Install¶

You need git, uv, and Rust for the ik and ball extras. If cargo --version finds nothing, install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then open a new terminal, so that cargo is on the PATH. On Windows, run the installer from rustup.rs instead.

Install deeperfly:

git clone https://github.com/NeLy-EPFL/deeperfly
cd deeperfly
uv tool install --editable --torch-backend auto ".[detect,ik,ball]"

This puts the deeperfly command on your PATH, to use from any folder. The command runs the code in the clone, so keep that folder. It also holds the example clips and configs, under examples/.

uv fetches Python 3.14 if the machine lacks it, and --torch-backend auto picks the PyTorch build for the machine's GPU, or the CPU build if there is none.

Check the installation:

deeperfly doctor

It lists what works: video decoding, each extra, and whether the detectors will run on a GPU.

Extras¶

The names in the brackets are optional parts. Leave out the ones you do not need.

Extra	What it adds	Needs
`detect`	The 2D detectors: `[pose2d]` and `deeperfly train`	a GPU for useful speed
`ik`	The body-model fit: `[ik]`	a Rust toolchain
`ball`	The treadmill ball: `[ball]`	a Rust toolchain. Its first run downloads SAM 3 (3.4 GB)

For instance, without the body model and the ball, no Rust is needed:

uv tool install --editable --torch-backend auto ".[detect]"

Without any extra, deeperfly still calibrates, labels, and reads and renders existing results. A run that asks for a missing extra's stage stops with the name of the extra to add.

Update¶

In the clone:

git pull
uv tool install --editable --reinstall --torch-backend auto ".[detect,ik,ball]"

List the same extras as when you installed. Do not use uv tool upgrade, which can replace the GPU build of PyTorch.

Uninstall¶

deeperfly cache clear    # delete the downloaded models and compiled kernels
uv tool uninstall deeperfly

Then delete the clone.

Download the models ahead of time¶

The released detectors are downloaded the first time a run names one. To fetch them all beforehand (about 1.2 GB), for a machine that will run without a network:

deeperfly models list            # list them
deeperfly models download --all  # download all

In the Ramdya lab, link the copy on the lab share instead:

ln -s /mnt/upramdya/data/TL/deeperfly-models ~/.cache/deeperfly/models

The cache¶

Downloaded models and compiled GUI kernels are kept in one folder: ~/.cache/deeperfly on Linux, ~/Library/Caches/deeperfly on macOS, and %LOCALAPPDATA%\deeperfly\Cache on Windows.

deeperfly cache info          # where it is, and how large
deeperfly cache clear         # delete all of it
deeperfly models remove NAME  # delete one model

Clearing only costs time: models are downloaded again, and kernels compiled again. To keep the cache elsewhere, such as on a cluster's scratch space:

export DEEPERFLY_CACHE_DIR=/scratch/$USER/deeperfly

Without a clone¶

To install straight from GitHub, without the examples:

uv tool install --torch-backend auto "deeperfly[detect,ik,ball] @ git+https://github.com/NeLy-EPFL/deeperfly"

And to update that installation:

uv tool install --reinstall --torch-backend auto "deeperfly[detect,ik,ball] @ git+https://github.com/NeLy-EPFL/deeperfly"

Developing deeperfly¶

To change deeperfly and run its tests, use the clone's own environment instead of the installed command:

uv sync --extra detect --extra ik --extra ball
uv run deeperfly doctor
uv run pytest -q

CONTRIBUTING.md has the checks a change must pass.