lerobot Documentation

File: docs/source/index.mdx Copy Chapter

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.

🤗 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 Copy Chapter

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 Copy Chapter

New here? See what a LeRobot dataset looks like before installing anything:

<a
target="_blank"
href="https://huggingface.co/spaces/lerobot/visualize_dataset?path=/lerobot/svla_so101_pickplace/episode_0"
class="shrink-0"

👀 See a dataset first


  Open <a
    target="_blank"
    href="https://huggingface.co/spaces/lerobot/visualize_dataset?path=/lerobot/svla_so101_pickplace/episode_0"
  >`lerobot/svla_so101_pickplace`</a> in the <a
    target="_blank"
    href="https://huggingface.co/spaces/lerobot/visualize_dataset"
  >LeRobot Dataset Visualizer</a> 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, then pick your path:

🔧 I have a robot

  LeRobot supports a wide range of arms and mobile robots. Popular picks:


  <li>
    [SO-101](./so101) - our flagship, low-cost arm
  </li>
  <li>
    [LeKiwi](./lekiwi) - a mobile base with an arm on top
  </li>
  <li>
    [Koch v1.1](./koch) - a long-time community favorite
  </li>
  <li>
    or find yours under **Robots** in the sidebar
  </li>


  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:


  <li>
    explore any dataset in the
    <a href="https://huggingface.co/spaces/lerobot/visualize_dataset">
      Dataset Visualizer
    </a>
  </li>
  <li>
    train on an existing
    <a href="https://huggingface.co/datasets?other=LeRobot">
      LeRobot dataset
    </a>
    from the Hub
  </li>
  <li>
    evaluate in [simulation](./envhub), against benchmarks like
    LIBERO or Meta-World
  </li>
  <li>
    try the free [Colab notebooks](./notebooks) - nothing to
    install
  </li>



🤝 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 Copy Chapter

<a
class="!no-underline border dark:border-gray-700 rounded-lg p-4 shadow hover:shadow-lg"
href="./cheat-sheet"

📋 Cheat Sheet

  Every LeRobot CLI command, copy-paste ready.

Which policy fits your GPU, and how long training takes.

Load, stream, and visualize robot datasets from the Hub.

A browser GUI for calibrating, recording, and training - no CLI required.

Start with ACT, our recommended first policy - or browse SmolVLA, π₀, and
  more in the sidebar.

Train and evaluate in simulated environments before touching real
  hardware.

Common Problems Copy Chapter

Running into issues? A few of the most frequent ones:

• Blurry or unusable camera footage - lighting matters more than resolution. See the Cameras guide.
• Build or install errors (cmake, ffmpeg, CUDA) - see the Troubleshooting section of the Installation guide.
• Not sure which policy fits your GPU - check the Compute & Hardware Guide.
• Still stuck? Ask on Discord - the community (and the LeRobot team) is there to help.

File: docs/source/installation.mdx Copy Chapter

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`](https://conda-forge.org/download/) Copy Chapter

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 Copy Chapter

Create a virtual environment with Python 3.12:

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

Install `ffmpeg` (for video decoding) Copy Section

LeRobot uses 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 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 🤗 Copy Chapter

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 Copy Section

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.

Installation from PyPI Copy Section

Core Library:
Install the base package with:

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) Copy Section

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 Copy Section

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 Copy Chapter

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 Copy Section

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

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

Motor Control Copy Section

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 Copy Section

Weights and Biases is included in the training extra. To use Weights and Biases for experiment tracking, log in with:

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 Copy Chapter

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:

pip install -e . -r docs-requirements.txt

You will also need nodejs. Please refer to their installation page

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 Copy Chapter

Once you have setup the doc-builder and additional packages, you can generate the documentation by
typing the following command:

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 Copy Chapter

To preview the docs, first install the watchdog module with:

pip install watchdog

Then run the following command:

doc-builder preview lerobot docs/source/

The docs will be viewable at 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 Copy Chapter

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 file.

Renaming section headers and moving sections Copy Chapter

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:

[ <a href="#section-b">Section A</a><a id="section-a"></a> ]

and of course, if you moved it to another file, then:

Sections that were moved:

[ <a href="../new-file#section-b">Section A</a><a id="section-a"></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.

Adding a new tutorial Copy Section

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 Copy Section

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 in which to place these files and reference
them by URL. We recommend putting them in the following dataset: 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.