Install LeRobot
There are two ways to get a runtime environment for LeRobot v0.5.0: use a prebuilt GPU image, or install from the official source locally. Use the image for training only; use the source install to modify policy configuration, debug data mapping, or connect a custom robot interface.
Roles and Prerequisites
Roles
| Role | Focus |
|---|---|
| Algorithm engineer | Source installation, policy configuration, dataset loading |
| Training operations | GPU images, container runtime, mounts, and ports |
Prerequisites
| Item | Requirement |
|---|---|
| Operating system | The source installation uses Ubuntu 22.04 as an example |
| Python | The source installation uses Python 3.12 or later; the official v0.5.0 declares requires-python as >=3.12 |
| GPU | Training requires an NVIDIA GPU and the NVIDIA container runtime |
| Video decoding | Requires ffmpeg; the default official decoding backend TorchCodec depends on it, and unsupported platforms fall back to pyav |
| Build tools | git, git-lfs, build-essential, cmake, ninja-build, python3-dev, and the FFmpeg development libraries |
| Disk | Room for datasets, dependencies, and checkpoints |
Procedure
- Confirm that the host can access the GPU inside a container.
docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubuntu22.04 nvidia-smi
- When using the image, pull and enter the platform LeRobot training image (default
lerobot:latest), and mount the dataset and output directories as separate volumes.
docker run --rm -it --gpus all --shm-size 16g \
-v /path/to/lerobot_dataset:/data/input \
-v /path/to/output:/outputs \
lerobot:latest \
bash
- Check the training entry point inside the container.
/lerobot/.venv/bin/lerobot-train --help
- For a source installation, install the system dependencies first.
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
- Create a Python 3.12 environment.
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel
- Install LeRobot v0.5.0 from the official tag.
git clone https://github.com/huggingface/lerobot.git
cd lerobot
git checkout v0.5.0
pip install -e ".[all]"
- Verify the installation. Start training only after all three commands return help output.
lerobot-train --help
lerobot-dataset-viz --help
lerobot-info
Verification
| Verification item | Method | Pass criteria |
|---|---|---|
| GPU visible | Run nvidia-smi inside the container | Lists the GPU model and driver |
| Training entry point available | Run lerobot-train --help | Prints parameter help with no import errors |
| Visualization entry point available | Run lerobot-dataset-viz --help | Prints parameter help |
| Dataset readable | Load the dataset root with LeRobotDataset | Returns the frame count and episode count with no exceptions |
| Video decodable | Open a dataset that contains MP4 | Frames decode |
Error Handling
| Symptom | Possible cause | Resolution | Owner |
|---|---|---|---|
| Dependency resolution failed | Python version below the declared requirement | Use Python 3.12 or later | Algorithm engineer |
| Video read failed | ffmpeg is missing | Install ffmpeg and reinstall the dependencies | Algorithm engineer |
| GPU not visible in the container | The NVIDIA container runtime is missing, or --gpus is not set | Install nvidia-container-toolkit and add --gpus all at runtime | Training operations |
| Slow image pull | Restricted network access to Docker Hub | Use the image address configured for the deployment | Training operations |
| PyTorch CUDA wheel download failed | The CUDA version does not match the driver | Install the matching version from the official PyTorch index first, then install LeRobot | Algorithm engineer |
| Dataset root not found | Wrong mount level | Mount the directory that contains meta/info.json and point --dataset.root to it | Algorithm engineer |