lerobot/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:

<!-- 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](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.

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](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))
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](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.