Installation
PyPI (pip / uv)
The base install includes OpenCV and covers all classical methods (Farneback, TV-L1, Lucas-Kanade):
To also enable deep learning methods (RAFT, SEA-RAFT, NeuFlow v2), install with the torch extra. This adds torch and torchvision as CPU builds by default:
For GPU-accelerated deep methods, install PyTorch separately first using the official instructions for your CUDA version, then install motionflow:
# Example: CUDA 12.4
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install motionflow
TV-L1 method
TV-L1 requires the OpenCV contrib modules, which are not included in opencv-python-headless. Install opencv-contrib-python-headless instead:
On conda-forge, opencv includes contrib by default so no additional step is needed.
conda-forge (conda / pixi / mamba)
The conda-forge package includes all dependencies including PyTorch. The solver automatically picks the correct GPU or CPU build based on your system:
Global tool install with Pixi
Pixi detects whether CUDA is available and installs the appropriate PyTorch variant automatically.
SEA-RAFT and NeuFlow v2: one-time setup
These two methods use research model architectures that are not on PyPI. After installing motionflow, run this once to download the architecture source files from their upstream GitHub repositories:
This only needs to be done once per installation. The files are placed inside the motionflow package directory. Model weights are then downloaded separately on first use (with a prompt). To force a re-download of the architecture files: