## File: docs/source/index.mdx # LeRobot **State-of-the-art machine learning for real-world robotics** 🤗 LeRobot provides a hardware-agnostic, Python-native interface for controlling real robots - from affordable arms like the SO-ARM101 to full humanoids. Plus the tools to record, store, and share the datasets they generate. Every dataset uses the standardized **LeRobotDataset** format (synchronized video + action/state data) and can be streamed directly from the [Hugging Face Hub](https://huggingface.co/lerobot). 🤗 On top of that data, LeRobot implements state-of-the-art policies - from lightweight imitation-learning models like ACT to large vision-language-action models like π₀ and SmolVLA - all trainable, shareable, and deployable with the same handful of CLI commands. The goal: lower the barrier to entry for robotics, so that everyone can contribute to, and benefit from, shared datasets and pretrained models. ## How It Works **Teleoperate → Record → Train → Deploy** 1. **Teleoperate** - control the robot yourself (with a leader arm, keyboard, or phone) so it can learn from your movements. 2. **Record** - each demonstration is saved as a dataset: synchronized camera video plus the actions you took. 3. **Train** - a policy (the neural network that will control the robot) learns to imitate your demonstrations. 4. **Deploy** - run the trained policy on the robot and watch it complete the task on its own. ## Get Started New here? See what a LeRobot dataset looks like before installing anything: 👀 See a dataset first Open `lerobot/svla_so101_pickplace` in the LeRobot Dataset Visualizer to watch its camera recordings next to the robot's state and actions, frame by frame, with nothing to install. It works for any LeRobot dataset on the Hub, including your own. See [how to use it](./using_dataset_tools#explore-a-dataset-in-the-browser). Ready to try it yourself? [Install LeRobot](./installation), then pick your path: 🔧 I have a robot LeRobot supports a wide range of arms and mobile robots. Popular picks:

[SO-101](./so101) - our flagship, low-cost arm

[LeKiwi](./lekiwi) - a mobile base with an arm on top

[Koch v1.1](./koch) - a long-time community favorite

or find yours under **Robots** in the sidebar

Once it's assembled and calibrated, record a dataset and train your first policy with the [imitation learning tutorial](./il_robots) - or skip the CLI entirely with [LeLab](./lelab), a browser GUI for the same workflow. 💻 No hardware yet You can still train and evaluate policies without owning a robot:

explore any dataset in the Dataset Visualizer

train on an existing LeRobot dataset from the Hub

evaluate in [simulation](./envhub), against benchmarks like LIBERO or Meta-World

try the free [Colab notebooks](./notebooks) - nothing to install

🤝 I want to contribute Start with the [Contributing guide](./contributing), then [add a new policy](./bring_your_own_policies) or [bring your own hardware](./integrate_hardware). ## Explore the Docs 📋 Cheat Sheet Every LeRobot CLI command, copy-paste ready. 🖥️ Compute & Hardware Guide Which policy fits your GPU, and how long training takes. 🗂️ LeRobotDataset Load, stream, and visualize robot datasets from the Hub. 🖼 LeLab A browser GUI for calibrating, recording, and training - no CLI required. 🧠 Policies Start with ACT, our recommended first policy - or browse SmolVLA, π₀, and more in the sidebar. 🎮 Simulation & Benchmarks Train and evaluate in simulated environments before touching real hardware. ## Common Problems Running into issues? A few of the most frequent ones: - **Blurry or unusable camera footage** - lighting matters more than resolution. See the [Cameras](./cameras) guide. - **Build or install errors** (`cmake`, `ffmpeg`, CUDA) - see the Troubleshooting section of the [Installation guide](./installation#troubleshooting). - **Not sure which policy fits your GPU** - check the [Compute & Hardware Guide](./hardware_guide). - **Still stuck?** Ask on [Discord](https://discord.gg/s3KuuzsPFb) - the community (and the LeRobot team) is there to help. --- ## File: docs/source/installation.mdx # 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-2-environment-setup). ## Step 1 (`conda` only): Install [`miniforge`](https://conda-forge.org/download/) ```bash 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: ```bash conda create -y -n lerobot python=3.12 ``` ```bash 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: ```bash conda activate lerobot ``` > [!NOTE] > When installing LeRobot inside WSL (Windows Subsystem for Linux), make sure to also install `evdev`: > > ```bash > conda install evdev -c conda-forge > ``` ```bash # Linux/macOS source .venv/bin/activate # Windows PowerShell .venv\Scripts\activate ``` > [!NOTE] > When installing LeRobot inside WSL (Windows Subsystem for Linux), make sure to also install `evdev`: > > ```bash > sudo apt install libevdev-dev > uv pip install evdev > ``` ### Install `ffmpeg` (for video decoding) LeRobot uses [TorchCodec](https://github.com/meta-pytorch/torchcodec) for video decoding by default, which requires `ffmpeg`. > [!NOTE] > **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`](https://github.com/huggingface/lerobot/blob/main/docker/Dockerfile.jetson) builds `torch`/`torchcodec` from source with CUDA support for JetPack 6.2 — community-maintained, see [`ravediamond/lerobot-jetson`](https://github.com/ravediamond/lerobot-jetson) for the prebuilt image and issue [#819](https://github.com/huggingface/lerobot/issues/819) for background. If your platform supports TorchCodec, install `ffmpeg` using one of the methods below: Install `ffmpeg` in your conda environment. This works with **all PyTorch versions** and is **required for PyTorch < 2.10**: ```bash conda install ffmpeg -c conda-forge ``` > [!TIP] > This usually installs `ffmpeg 8.X` with the `libsvtav1` encoder. If you run into issues (e.g. `libsvtav1` missing — check with `ffmpeg -encoders` — or a version mismatch with `torchcodec`), you can explicitly install `ffmpeg 7.1.1` using: > > ```bash > conda install ffmpeg=7.1.1 -c conda-forge > ``` Starting with **PyTorch >= 2.10** (TorchCodec ≥ 0.10), TorchCodec can dynamically link to a system-wide `ffmpeg` installation. This is useful when using `uv` or other non-`conda` environment managers: ```bash # Ubuntu/Debian sudo apt install ffmpeg # macOS (Apple Silicon) brew install ffmpeg ``` > [!IMPORTANT] > System-wide `ffmpeg` is **only supported with PyTorch >= 2.10** (TorchCodec ≥ 0.10). For older PyTorch versions, you **must** use `conda install ffmpeg -c conda-forge` instead. ## 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: ```bash 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. ```bash 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) ``` ```bash 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: ```bash pip install lerobot ``` ```bash 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. | Extra | What it adds | Typical use case | | ---------- | ------------------------------------------- | ----------------------------------- | | `dataset` | `datasets`, `av`, `torchcodec`, `jsonlines` | Loading & creating datasets | | `training` | `dataset` + `accelerate`, `wandb` | Training policies | | `hardware` | `pynput`, `pyserial`, `deepdiff` | Connecting to real robots | | `viz` | `rerun-sdk` | Visualization during recording/eval | **Composite Extras** combine feature extras for common CLI scripts: | Extra | Includes | Typical use case | | -------------- | ------------------------------ | ------------------------------------------------------- | | `core_scripts` | `dataset` + `hardware` + `viz` | `lerobot-record`, `lerobot-replay`, `lerobot-calibrate` | | `evaluation` | `av` | `lerobot-eval` (add policy + env extras as needed) | | `dataset_viz` | `dataset` + `viz` | `lerobot-dataset-viz`, `lerobot-imgtransform-viz` | ```bash 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: ```bash 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. **Source install via `uv` (`uv sync` or `uv pip install -e .`)** `torch` and `torchvision` are pinned by the project to the **CUDA 12.8** PyTorch index (`https://download.pytorch.org/whl/cu128`, driver floor **570.86**) — covers Ampere/Ada/Hopper/Blackwell GPUs. No action needed for typical NVIDIA setups. To override for a different CUDA variant: ```bash uv pip install --force-reinstall torch torchvision \ --index-url https://download.pytorch.org/whl/cu126 # older drivers; or cu130 for Blackwell on driver ≥ 580 ``` **Source install via `pip`/`conda`, or `pip install lerobot` from PyPI** PyPI default torch wheel is currently a cu130-bundled Linux wheel, driver floor **580.65**. To pick a specific CUDA variant: **Using `pip` or `conda`** — install torch first with an explicit index, then lerobot: ```bash pip install --index-url https://download.pytorch.org/whl/cu128 torch torchvision pip install -e ".[all]" # source # — or — pip install lerobot # from PyPI ``` **Using `uv` to install from PyPI** — one-liner via `--torch-backend` (uv ≥ 0.6): ```bash uv pip install --torch-backend cu128 lerobot ``` Supported values include `auto`, `cpu`, `cu126`, `cu128`, `cu129`, `cu130`, plus various `rocm*` and `xpu`. Swap as needed for your driver. ### 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: ```bash 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](https://pyav.org/docs/develop/overview/installation.html#bring-your-own-ffmpeg) ## 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](https://github.com/huggingface/gym-aloha)), or `pusht` ([gym-pusht](https://github.com/huggingface/gym-pusht)). These automatically include the `dataset` extra. ```bash 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](https://github.com/pollen-robotics/rustypot). ```bash pip install -e ".[feetech]" # or "[dynamixel]" for example ``` ### Experiment Tracking Weights and Biases is included in the `training` extra. To use [Weights and Biases](https://docs.wandb.ai/quickstart) for experiment tracking, log in with: ```bash wandb login ``` You can now assemble your robot if it's not ready yet, look for your robot type on the left. Then follow the link below to use Lerobot with your robot. --- ## File: docs/README.md # Generating the documentation To generate the documentation, you first have to build it. Several packages are necessary to build the doc, you can install them with the following command, at the root of the code repository: ```bash pip install -e . -r docs-requirements.txt ``` You will also need `nodejs`. Please refer to their [installation page](https://nodejs.org/en/download) --- **NOTE** You only need to generate the documentation to inspect it locally (if you're planning changes and want to check how they look before committing for instance). You don't have to `git commit` the built documentation. --- ## Building the documentation Once you have setup the `doc-builder` and additional packages, you can generate the documentation by typing the following command: ```bash doc-builder build lerobot docs/source/ --build_dir ~/tmp/test-build ``` You can adapt the `--build_dir` to set any temporary folder that you prefer. This command will create it and generate the MDX files that will be rendered as the documentation on the main website. You can inspect them in your favorite Markdown editor. ## Previewing the documentation To preview the docs, first install the `watchdog` module with: ```bash pip install watchdog ``` Then run the following command: ```bash doc-builder preview lerobot docs/source/ ``` The docs will be viewable at [http://localhost:3000](http://localhost:3000). You can also preview the docs once you have opened a PR. You will see a bot add a comment to a link where the documentation with your changes lives. --- **NOTE** The `preview` command only works with existing doc files. When you add a completely new file, you need to update `_toctree.yml` & restart `preview` command (`ctrl-c` to stop it & call `doc-builder preview ...` again). --- ## Adding a new element to the navigation bar Accepted files are Markdown (.md). Create a file with its extension and put it in the source directory. You can then link it to the toc-tree by putting the filename without the extension in the [`_toctree.yml`](https://github.com/huggingface/lerobot/blob/main/docs/source/_toctree.yml) file. ## Renaming section headers and moving sections It helps to keep the old links working when renaming the section header and/or moving sections from one document to another. This is because the old links are likely to be used in Issues, Forums, and Social media and it'd make for a much more superior user experience if users reading those months later could still easily navigate to the originally intended information. Therefore, we simply keep a little map of moved sections at the end of the document where the original section was. The key is to preserve the original anchor. So if you renamed a section from: "Section A" to "Section B", then you can add at the end of the file: ``` Sections that were moved: [ Section A ] ``` and of course, if you moved it to another file, then: ``` Sections that were moved: [ Section A ] ``` Use the relative style to link to the new file so that the versioned docs continue to work. For an example of a rich moved sections set please see the very end of [the transformers Trainer doc](https://github.com/huggingface/transformers/blob/main/docs/source/en/main_classes/trainer.md). ### Adding a new tutorial Adding a new tutorial or section is done in two steps: - Add a new file under `./source`. This file can either be ReStructuredText (.rst) or Markdown (.md). - Link that file in `./source/_toctree.yml` on the correct toc-tree. Make sure to put your new file under the proper section. If you have a doubt, feel free to ask in a Github Issue or PR. ### Writing source documentation Values that should be put in `code` should either be surrounded by backticks: \`like so\`. Note that argument names and objects like True, None or any strings should usually be put in `code`. #### Writing a multi-line code block Multi-line code blocks can be useful for displaying examples. They are done between two lines of three backticks as usual in Markdown: ```` ``` # first line of code # second line # etc ``` ```` #### Adding an image Due to the rapidly growing repository, it is important to make sure that no files that would significantly weigh down the repository are added. This includes images, videos, and other non-text files. We prefer to leverage a hf.co hosted `dataset` like the ones hosted on [`hf-internal-testing`](https://huggingface.co/hf-internal-testing) in which to place these files and reference them by URL. We recommend putting them in the following dataset: [huggingface/documentation-images](https://huggingface.co/datasets/huggingface/documentation-images). If an external contribution, feel free to add the images to your PR and ask a Hugging Face member to migrate your images to this dataset.