Installation

Ce guide utilise conda (via miniforge) pour gérer les environnements (recommandé). Si vous préférez un autre gestionnaire d’environnements (par exemple uv, venv), assurez-vous d’avoir Python >=3.12, puis passez directement à Configuration de l’environnement.

Étape 1 (conda uniquement) : Installer miniforge

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Étape 2 : Configuration de l'environnement

Créer un environnement virtuel avec Python 3.12 :

conda create -y -n lerobot python=3.12

uv python install 3.12
uv venv --python 3.12

Puis activez votre environnement virtuel, vous devez le faire à chaque fois que vous ouvrez un shell pour utiliser lerobot :

conda activate lerobot

# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\activate

Exigences de la plateforme

Sur Apple Silicon, PyTorch nécessite macOS 14 ou une version ultérieure, et l’accélération MPS macOS 15 ou une version ultérieure (sur macOS 14, LeRobot bascule sur le CPU). Sur Linux, les roues PyTorch par défaut exigent un pilote NVIDIA de 580.65 ou une version ultérieure ; pour les pilotes plus anciens, consultez PyTorch CUDA variant.

Installer ffmpeg (pour le décodage vidéo)

LeRobot utilise TorchCodec par défaut pour le décodage vidéo, ce qui nécessite ffmpeg.

Prise en charge des plateformes : TorchCodec n'est pas disponible sur macOS Intel (x86_64) ni sur Linux armv7l. Sur ces plateformes, LeRobot bascule automatiquement sur pyav — vous n'avez donc pas besoin d'installer ffmpeg et pouvez passer directement à l'étape 3.

Jetson (aarch64 + CUDA) : le décodage vidéo s’exécute par défaut sur le CPU. docker/Dockerfile.jetson compile torch/torchcodec depuis le code source avec prise en charge de CUDA pour JetPack 6.2 — maintenu par la communauté, voir ravediamond/lerobot-jetson pour l’image préconstruite et le problème #819 pour le contexte.

Si votre plateforme prend en charge TorchCodec, installez ffmpeg à l'aide de l'une des méthodes ci-dessous :

conda install ffmpeg -c conda-forge

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

Étape 3 : Installer LeRobot 🤗

L'installation de base de lerobot est volontairement légère — elle ne contient que les dépendances ML essentielles (PyTorch, torchvision, numpy, opencv, einops, draccus, huggingface-hub, gymnasium, safetensors). Les dépendances plus lourdes sont conditionnées par des extras optionnels afin que vous n'installiez que ce dont vous avez besoin.

À partir de la source

Tout d'abord, clonez le dépôt et accédez au répertoire :

git clone https://github.com/huggingface/lerobot.git
cd lerobot

Ensuite, installez la bibliothèque en mode éditable. Cela est utile si vous prévoyez de contribuer au code.

pip install -e ".[core_scripts]"  # For robot workflows (recording, replaying, calibrate)
pip install -e ".[training]"      # For training policies
pip install -e ".[all]"           # Everything (all policies, envs, hardware, dev tools)

uv pip install -e ".[core_scripts]"  # For robot workflows (recording, replaying, calibrate)
uv pip install -e ".[training]"      # For training policies
uv pip install -e ".[all]"           # Everything (all policies, envs, hardware, dev tools)

Installation depuis PyPI

Bibliothèque principale : installez le package de base avec :

pip install lerobot

uv pip install lerobot

Cette installation ne comprend que les dépendances ML de base. Vous devrez ajouter des extras pour la plupart des workflows.

Extras de fonctionnalités : LeRobot fournit des extras par fonctionnalité correspondant aux flux de travail courants. Si vous utilisez uv, remplacez pip install par uv pip install dans les commandes ci-dessous.

Composite Extras combinent les extras de fonctionnalités pour les scripts CLI courants :

pip install 'lerobot[core_scripts]'          # Record, replay, calibrate
pip install 'lerobot[training]'              # Train policies
pip install 'lerobot[core_scripts,training]' # Record + train
pip install 'lerobot[all]'                   # Everything

Compléments pour les politiques, les environnements et le matériel restent disponibles pour des dépendances spécifiques :

pip install 'lerobot[pi]'             # Pi0/Pi0.5/Pi0-FAST policy deps
pip install 'lerobot[smolvla]'        # SmolVLA policy deps
pip install 'lerobot[diffusion]'      # Diffusion policy deps (diffusers)
pip install 'lerobot[aloha,pusht]'    # Simulation environments
pip install 'lerobot[feetech]'        # Feetech motor support

Plusieurs extras peuvent être combinés (par exemple, .[core_scripts,pi,pusht]). Pour la liste complète des extras disponibles, reportez-vous à pyproject.toml.

Variante CUDA de PyTorch (Linux uniquement)

Sur Linux, torch et torchvision proviennent de PyPI, dont les roues par défaut sont des builds CUDA 13 (pilote minimal 580.65). Les installations sur macOS et Windows utilisent les roues par défaut de PyPI et peuvent ignorer cette section.

Pour un pilote ou un GPU plus ancien, installez d’abord PyTorch depuis l’index PyTorch correspondant, puis LeRobot. La version Linux de TorchCodec sur PyPI est également une compilation CUDA 13, il faut donc la prendre depuis l’index CPU (avec torch inférieur à 2.11, choisissez la version correspondante dans le tableau de compatibilité TorchCodec) :

pip install --index-url https://download.pytorch.org/whl/cu126 torch torchvision
pip install --index-url https://download.pytorch.org/whl/cpu torchcodec
pip install -e ".[all]"          # source
# — or —
pip install lerobot              # from PyPI

cu126 est la version de PyTorch conservée pour les pilotes qui ne prennent en charge que CUDA 12. torch 2.15 ne propose pas de version CUDA 12, cet index installe donc torch 2.14, et rester sur CUDA 12 signifie rester sur torch 2.14 ou une version antérieure.

Avec uv pip, --torch-backend sélectionne l’index en une seule étape, par exemple uv pip install --torch-backend cu126 lerobot. uv sync installe toujours le verrouillage engagé : pour modifier la compilation CUDA, ajoutez l’index à [tool.uv.index] et [tool.uv.sources] dans pyproject.toml et relancez uv lock.

Dépannage

En cas d'erreurs de compilation, vous devrez peut-être installer des dépendances système supplémentaires : cmake, build-essential et ffmpeg libs. Pour les installer sur Linux, exécutez :

sudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev

Pour les autres systèmes, voir : Compilation de PyAV

Dépendances facultatives

LeRobot propose des extras optionnels pour des fonctionnalités spécifiques. Plusieurs extras peuvent être combinés (par exemple, .[aloha,feetech]). Pour consulter tous les extras disponibles, reportez-vous à pyproject.toml. Si vous utilisez uv, remplacez pip install par uv pip install dans les commandes ci-dessous.

Simulations

Installer les paquets de l’environnement : aloha (gym-aloha), pusht (gym-pusht), libero (Linux uniquement) ou metaworld. Ces derniers incluent automatiquement l’extra dataset.

pip install -e ".[aloha]" # or "[pusht]" for example

Contrôle moteur

Installez l’extension pour vos moteurs : dynamixel pour Koch v1.1, feetech pour SO100/SO101/Moss. Les deux communiquent avec les moteurs via rustypot.

pip install -e ".[feetech]" # or "[dynamixel]" for example

Suivi des expériences

Trackio est inclus dans l’extra training. Les exécutions locales ne nécessitent ni compte ni connexion : elles sont stockées dans une base de données SQLite locale sous ~/.cache/huggingface/trackio. Ouvrez le tableau de bord avec :

trackio show --project lerobot

Pour synchroniser les exécutions vers un Space Hugging Face (créé s’il est manquant), exécutez hf auth login et passez --trackio.space_id=<user>/<space>. Les tâches distantes (--job.target) avec le suivi activé nécessitent space_id, car la base de données locale du pod est perdue à la fin de la tâche.

La confidentialité de l’espace est par défaut None : les nouveaux espaces sont publics, sauf si le paramètre par défaut de l’organisation est privé. Passez --trackio.private=true pour créer un espace privé.

Chaque exécution enregistre la commande qui l’a lancée ainsi que sa sortie console (affichages, journaux, traces d’erreurs), les deux étant affichés sur la page de l’exécution dans le tableau de bord. Sur un Space, ils sont aussi visibles que le Space lui-même ; passez --trackio.capture_console=false pour exclure la sortie console de l’exécution.

Migration depuis Weights & Biases

Étapes suivantes

• Vous avez un robot ? Assemblez-le et calibrez-le en suivant sa page sous Robots dans la barre latérale (par exemple SO-101), puis enregistrez un jeu de données et entraînez votre première politique avec le tutoriel sur l’apprentissage par imitation.
• Pas encore de matériel ? Entraînez et évaluez une politique en simulation avec LIBERO, ou essayez les notebooks Colab.
• Envie de contribuer ? Consultez le guide de contribution.
• Gardez le cheat sheet à portée de main : il répertorie toutes les commandes LeRobot en un seul endroit.