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, 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

Platform requirements

On Apple Silicon, PyTorch requires macOS 14 or newer, and MPS acceleration macOS 15 or newer (on macOS 14, LeRobot falls back to CPU). On Linux, the default PyTorch wheels need an NVIDIA driver of 580.65 or newer; for older drivers, see PyTorch CUDA variant.

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) or Linux armv7l. 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): video decoding runs on CPU 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, torch and torchvision come from PyPI, whose default wheels are CUDA 13 builds (driver floor 580.65). macOS and Windows installs use the PyPI default wheels and can skip this section.

For an older driver or GPU, install PyTorch from the matching PyTorch index first, then LeRobot. PyPI’s Linux TorchCodec is a CUDA 13 build too, so take it from the CPU index (with torch below 2.11, pick the matching release from the TorchCodec compatibility table):

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 is the build PyTorch keeps for drivers that only support CUDA 12. torch 2.15 has no CUDA 12 build, so this index installs torch 2.14, and staying on CUDA 12 means staying on torch 2.14 or older.

With uv pip, --torch-backend selects the index in one step, e.g. uv pip install --torch-backend cu126 lerobot. uv sync always installs the committed lock: to change the CUDA build there, add the index to [tool.uv.index] and [tool.uv.sources] in pyproject.toml and re-run uv lock.

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.