Skip to main content

Install LeRobot

This guide targets LeRobot v0.5.0. In that release, pyproject.toml declares:

  • Python >=3.12
  • Package version lerobot==0.5.0
  • Training entry point after install: lerobot-train
  • Dataset visualization: lerobot-dataset-viz
  • Recording / replay / info CLIs: lerobot-record, lerobot-replay, lerobot-info, etc.

Use the installed lerobot-train command for training—do not rely on ad-hoc python .../train.py snippets from older blog posts.

For training only, use IO-AI’s published image ioaitech/lerobot-gpu:v0.5.0. It bundles LeRobot v0.5.0, GPU training dependencies, a video decoding stack, and the lerobot-train CLI.

docker run --rm -it --gpus all --shm-size 16g \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/outputs \
  ioaitech/lerobot-gpu:v0.5.0 \
  bash

Inside the container:

lerobot-info
lerobot-train --help

Install from source​

Use a source install when you need to patch LeRobot, debug policy configs, or integrate custom robots.

1. System dependencies (Ubuntu / Debian)​

sudo apt-get update
sudo apt-get install -y \
  git git-lfs curl build-essential cmake pkg-config ninja-build \
  ffmpeg python3-dev \
  libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev \
  libswscale-dev libswresample-dev libavfilter-dev

2. Python 3.12 environment​

Minimal venv workflow:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel

If Python 3.12 is not on the host, use conda:

conda create -y -n lerobot python=3.12
conda activate lerobot

If pip install is slow or times out, configure a regional package index or follow your organization’s proxy policy. For CUDA wheels, follow the official PyTorch install guide for your CUDA version, then install LeRobot.

3. Install LeRobot v0.5.0​

Pin the upstream tag:

git clone https://github.com/huggingface/lerobot.git
cd lerobot
git checkout v0.5.0

pip install -e .

SmolVLA training:

pip install -e ".[smolvla]"

Most optional stacks (larger footprint):

pip install -e ".[all]"

The smolvla extra pulls transformers, num2words, accelerate, safetensors, etc. The all extra installs broader robot, sim, policy, and dev dependencies and takes longer.

4. Verify the install​

lerobot-info
lerobot-train --help
lerobot-dataset-viz --help

Only start long runs after the CLIs work.

FAQ​

Why Python 3.12​

pyproject.toml sets requires-python = ">=3.12". Older Python versions may fail dependency resolution or behave differently at runtime.

Why ffmpeg matters​

LeRobot datasets often use MP4 video. Training and visualization may decode video. Confirm:

ffmpeg -version

--policy.type vs --policy.path​

Train a policy family from scratch with --policy.type=act, --policy.type=diffusion, etc. Fine-tune from a pretrained checkpoint with --policy.path=lerobot/smolvla_base (per the official SmolVLA guide).

References​