ContextQMD
Back to Lerobot

Installation

docs/source/installation.mdx

0.5.16.2 KB
Original Source

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

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:

<!-- prettier-ignore-start --> <hfoptions id="create_venv"> <hfoption id="conda"> ```bash conda create -y -n lerobot python=3.12 ``` </hfoption> <hfoption id="uv (PyTorch >= 2.10 only)"> ```bash uv python install 3.12 uv venv --python 3.12 ``` </hfoption> </hfoptions> <!-- prettier-ignore-end -->

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

<!-- prettier-ignore-start --> <hfoptions id="activate_venv"> <hfoption id="conda"> ```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
</hfoption> <hfoption id="uv (PyTorch >= 2.10 only)"> ```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
</hfoption> </hfoptions> <!-- prettier-ignore-end -->

Install ffmpeg (for video decoding)

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.

If your platform supports TorchCodec, install ffmpeg using one of the methods below:

<!-- prettier-ignore-start --> <hfoptions id="install_ffmpeg"> <hfoption id="conda (any PyTorch version)">

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
</hfoption> <hfoption id="uv (PyTorch >= 2.10 only)">

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.

</hfoption> </hfoptions> <!-- prettier-ignore-end -->

Step 3: Install LeRobot 🤗

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.

<!-- prettier-ignore-start --> <hfoptions id="install_lerobot_src"> <hfoption id="conda"> ```bash pip install -e . ``` </hfoption> <hfoption id="uv"> ```bash uv pip install -e . ``` </hfoption> </hfoptions> <!-- prettier-ignore-end -->

Installation from PyPI

Core Library: Install the base package with:

<!-- prettier-ignore-start --> <hfoptions id="install_lerobot_pypi"> <hfoption id="conda"> ```bash pip install lerobot ``` </hfoption> <hfoption id="uv"> ```bash uv pip install lerobot ``` </hfoption> </hfoptions> <!-- prettier-ignore-end -->

This installs only the default dependencies.

Extra Features: To install additional functionality, use one of the following (If you are using uv, replace pip install with uv pip install in the commands below.):

bash
pip install 'lerobot[all]'          # All available features
pip install 'lerobot[aloha,pusht]'  # Specific features (Aloha & Pusht)
pip install 'lerobot[feetech]'      # Feetech motor support

Replace [...] with your desired features.

Available Tags: For a full list of optional dependencies, see: https://pypi.org/project/lerobot/

Troubleshooting

If you encounter build errors, you may need to install additional 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

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), or pusht (gym-pusht) Example:

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

Motor Control

For Koch v1.1 install the Dynamixel SDK, for SO100/SO101/Moss install the Feetech SDK.

bash
pip install -e ".[feetech]" # or "[dynamixel]" for example

Experiment Tracking

To use Weights and Biases 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.