From b6e60a6e308bbe9abf7fa18fa749d99f9a774be8 Mon Sep 17 00:00:00 2001 From: Caroline Pascal Date: Sun, 5 Apr 2026 19:24:43 +0200 Subject: [PATCH] chore(dependencies): bump minimum torch from 2.2.1 to 2.7 (#3156) * feat(ffmpeg): updating ffmpeg verion to 8.X * Revert "feat(ffmpeg): updating ffmpeg verion to 8.X" This reverts commit bb0f03185c43eedb0d853b27b26f346a24840945. * chore(pyproject): updating pyproject to fit the minimally required version of torchcodec * chore(docs): updating doc with specific instructions for ffmpeg/torchcodec installation * fix(typo): reverting ceiling bound on pytorch to 2.11.0 * chore(format): removing empty line * chore(typo): fixing typo * chore(docs): adding warning in case of torchcodec/ffmpeg version mismatch * chore(docs): applying comments * chore(docs): adding uv commands for evdev on WSL * fix(typo): fixing typo * fix(typo): fixing typos again * chore(ruff): format * fix(evdev install): splitting evdev install instructions between conda and uv * chore(ruff): format --------- Co-authored-by: Steven Palma --- docs/source/installation.mdx | 105 ++++++++++++++++++++++++----------- pyproject.toml | 6 +- 2 files changed, 75 insertions(+), 36 deletions(-) diff --git a/docs/source/installation.mdx b/docs/source/installation.mdx index 80f705e88..a988523b5 100644 --- a/docs/source/installation.mdx +++ b/docs/source/installation.mdx @@ -1,6 +1,6 @@ # Installation -This guide uses `conda` (via miniforge) to manage environments (recommended). If you prefer another environment manager (e.g. `uv`, `venv`), ensure you have Python >=3.12 and `ffmpeg` installed with the `libsvtav1` encoder, then skip ahead to [Environment Setup](#step-2-environment-setup). +This guide uses `conda` (via miniforge) to manage environments (recommended). If you prefer another environment manager (e.g. `uv`, `venv`), ensure you have Python >=3.12 and support PyTorch >= 2.10, then skip ahead to [Environment Setup](#step-2-environment-setup). ## Step 1 (`conda` only): Install [`miniforge`](https://conda-forge.org/download/) @@ -20,7 +20,7 @@ Create a virtual environment with Python 3.12: conda create -y -n lerobot python=3.12 ``` - + ```bash uv python install 3.12 uv venv --python 3.12 @@ -32,48 +32,87 @@ uv venv --python 3.12 Then activate your virtual environment, you have to do this each time you open a shell to use lerobot: + -```bash + +```bash conda activate lerobot -``` - -```bash -# Linux/macOSsource -source .venv/bin/activate -# Windows PowerShell -source .venv\Scripts\Activate.ps1 ``` - - - - -When using `conda`, install `ffmpeg` in your environment: - -```bash -conda install ffmpeg -c conda-forge -ffmpeg -version # ffmpeg 8.X is not yet supported ! -``` - -> [!TIP] -> This usually installs `ffmpeg 7.X` for your platform compiled with the `libsvtav1` encoder. If `libsvtav1` is not supported (check supported encoders with `ffmpeg -encoders`), you can: -> -> - _[On any platform]_ Explicitly install `ffmpeg 7.X` using: -> -> ```bash -> conda install ffmpeg=7.1.1 -c conda-forge -> ``` -> -> - _[On Linux only]_ If you want to bring your own ffmpeg: Install [ffmpeg build dependencies](https://trac.ffmpeg.org/wiki/CompilationGuide/Ubuntu#GettheDependencies) and [compile ffmpeg from source with libsvtav1](https://trac.ffmpeg.org/wiki/CompilationGuide/Ubuntu#libsvtav1), and make sure you use the corresponding ffmpeg binary to your install with `which ffmpeg`. > [!NOTE] -> When installing LeRobot inside WSL (Windows Subsystem for Linux), make sure to install `evdev` with the following command: +> When installing LeRobot inside WSL (Windows Subsystem for Linux), make sure to also install `evdev`: > > ```bash > conda install evdev -c conda-forge > ``` + + +```bash +# Linux/macOS +source .venv/bin/activate +# Windows PowerShell +.venv\Scripts\activate +``` + +> [!NOTE] +> When installing LeRobot inside WSL (Windows Subsystem for Linux), make sure to also install `evdev`: +> +> ```bash +> sudo apt install libevdev-dev +> uv pip install evdev +> ``` + + + + + +### Install `ffmpeg` (for video decoding) + +LeRobot uses [TorchCodec](https://github.com/meta-pytorch/torchcodec) for video decoding by default, which requires `ffmpeg`. + +> [!NOTE] +> **Platform support:** TorchCodec is **not available** on macOS Intel (x86_64), Linux ARM (aarch64, arm64, armv7l), or Windows with PyTorch < 2.8. On these platforms, LeRobot automatically falls back to `pyav` — so you do not need to install `ffmpeg` and can skip to Step 3. + +If your platform supports TorchCodec, install `ffmpeg` using one of the methods below: + + + + + + +Install `ffmpeg` in your conda environment. This works with **all PyTorch versions** and is **required for PyTorch < 2.10**: + +```bash +conda install ffmpeg -c conda-forge +``` + +> [!TIP] +> This usually installs `ffmpeg 8.X` with the `libsvtav1` encoder. If you run into issues (e.g. `libsvtav1` missing — check with `ffmpeg -encoders` — or a version mismatch with `torchcodec`), you can explicitly install `ffmpeg 7.1.1` using: +> +> ```bash +> conda install ffmpeg=7.1.1 -c conda-forge +> ``` + + + + +Starting with **PyTorch >= 2.10** (TorchCodec ≥ 0.10), TorchCodec can dynamically link to a system-wide `ffmpeg` installation. This is useful when using `uv` or other non-`conda` environment managers: + +```bash +# Ubuntu/Debian +sudo apt install ffmpeg + +# macOS (Apple Silicon) +brew install ffmpeg +``` + > [!IMPORTANT] -> If you are using `uv` you will have to install `ffmpeg` system-wide (outside of the virtual environment). You rely on `uv` and `torchcodec` ability to dynamically link to the system `ffmpeg`. +> System-wide `ffmpeg` is **only supported with PyTorch >= 2.10** (TorchCodec ≥ 0.10). For older PyTorch versions, you **must** use `conda install ffmpeg -c conda-forge` instead. + + + + ## Step 3: Install LeRobot 🤗 diff --git a/pyproject.toml b/pyproject.toml index 4a1efab30..c299199c7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -71,9 +71,9 @@ dependencies = [ "cmake>=3.29.0.1,<4.2.0", "packaging>=24.2,<26.0", - "torch>=2.2.1,<2.11.0", - "torchcodec>=0.2.1,<0.11.0; sys_platform != 'win32' and (sys_platform != 'linux' or (platform_machine != 'aarch64' and platform_machine != 'arm64' and platform_machine != 'armv7l')) and (sys_platform != 'darwin' or platform_machine != 'x86_64')", - "torchvision>=0.21.0,<0.26.0", + "torch>=2.7,<2.11.0", + "torchcodec>=0.3.0,<0.11.0; sys_platform != 'win32' and (sys_platform != 'linux' or (platform_machine != 'aarch64' and platform_machine != 'arm64' and platform_machine != 'armv7l')) and (sys_platform != 'darwin' or platform_machine != 'x86_64')", # NOTE: Windows support starts at version 0.7 (needs torch==2.8), ffmpeg>=8 support starts at version 0.8.1 (needs torch==2.9), system-wide ffmpeg support starts at version 0.10 (needs torch==2.10). + "torchvision>=0.22.0,<0.26.0", "einops>=0.8.0,<0.9.0", "opencv-python-headless>=4.9.0,<4.14.0",