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 support PyTorch >= 2.10, then skip ahead to Environment Setup.

Step 1 ( conda only): Install miniforge

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

Step 2: Environment Setup

Create a virtual environment with Python 3.12:

conda create -y -n lerobot python=3.12

uv python install 3.12
uv venv --python 3.12

Then activate your virtual environment, you have to do this each time you open a shell to use lerobot:

conda activate lerobot

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

Install ffmpeg (for video decoding)

LeRobot uses TorchCodec for video decoding by default, which requires ffmpeg.

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.

Jetson (aarch64 + CUDA): the pyav fallback above means no GPU-accelerated video decode by default. docker/Dockerfile.jetson builds torch/torchcodec from source with CUDA support for JetPack 6.2 — community-maintained, see ravediamond/lerobot-jetson for the prebuilt image and issue #819 for background.

If your platform supports TorchCodec, install ffmpeg using one of the methods below:

conda install ffmpeg -c conda-forge

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

Step 3: Install LeRobot 🤗

The base lerobot install is intentionally lightweight — it includes only core ML dependencies (PyTorch, torchvision, numpy, opencv, einops, draccus, huggingface-hub, gymnasium, safetensors). Heavier dependencies are gated behind optional extras so you only install what you need.

From Source

First, clone the repository and navigate into the directory:

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

Then, install the library in editable mode. This is useful if you plan to contribute to the 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 from PyPI

Core Library: Install the base package with:

pip install lerobot

uv pip install lerobot

This installs only the core ML dependencies. You will need to add extras for most workflows.

Feature Extras: LeRobot provides feature-scoped extras that map to common workflows. If you are using uv, replace pip install with uv pip install in the commands below.

Composite Extras combine feature extras for common CLI scripts:

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

Policy, environment, and hardware extras are still available for specific dependencies:

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

Multiple extras can be combined (e.g., .[core_scripts,pi,pusht]). For a full list of available extras, refer to pyproject.toml.

PyTorch CUDA variant (Linux only)

On Linux, the install path determines which CUDA wheel you get. macOS and Windows installs use the PyPI default (MPS / CPU / CUDA-Windows wheel respectively) and can skip this section.

uv pip install --force-reinstall torch torchvision \
    --index-url https://download.pytorch.org/whl/cu126   # older drivers; or cu130 for Blackwell on driver ≥ 580

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

uv pip install --torch-backend cu128 lerobot

Troubleshooting

If you encounter build errors, you may need to install additional system dependencies: cmake, build-essential, and ffmpeg libs. To install these for Linux run:

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

For other systems, see: Compiling PyAV

Optional dependencies

LeRobot provides optional extras for specific functionalities. Multiple extras can be combined (e.g., .[aloha,feetech]). For all available extras, refer to pyproject.toml. If you are using uv, replace pip install with uv pip install in the commands below.

Simulations

Install environment packages: aloha (gym-aloha), pusht (gym-pusht), libero (Linux only) or metaworld. These automatically include the dataset extra.

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

Motor Control

Install the extra for your motors: dynamixel for Koch v1.1, feetech for SO100/SO101/Moss. Both talk to the motors through rustypot.

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

Experiment Tracking

Trackio is included in the training extra. Local runs need no account or login: they are stored in a local SQLite database under ~/.cache/huggingface/trackio. Open the dashboard with:

trackio show --project lerobot

To sync runs to a Hugging Face Space (created if missing), run hf auth login and pass --trackio.space_id=<user>/<space>. Remote jobs (--job.target) with tracking enabled require space_id, because the pod’s local database is lost when the job ends.

Space privacy defaults to None: new Spaces are public unless the organization’s default is private. Pass --trackio.private=true to create a private Space.

Each run records the command that launched it and its console output (prints, logs, tracebacks), both shown on the run’s page in the dashboard. On a Space they are as visible as the Space itself; pass --trackio.capture_console=false to keep the console output out of the run.

Migrating from Weights & Biases

Next steps

• Have a robot? Assemble and calibrate it by following its page under Robots in the sidebar (for example SO-101), then record a dataset and train your first policy with the imitation learning tutorial.
• No hardware yet? Train and evaluate a policy in simulation with LIBERO, or try the Colab notebooks.
• Want to contribute? Read the contributing guide.
• Keep the cheat sheet at hand: it lists every LeRobot command in one place.