安装

本指南使用 conda（通过 miniforge）来管理环境（推荐）。如果您更喜欢其他环境管理器（例如 uv、venv），请确保您有 Python >=3.12 并支持 PyTorch >= 2.10，然后跳到环境设置。

步骤 1（仅 `conda`）：安装 `miniforge`

wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

步骤 2：环境设置

使用 Python 3.12 创建虚拟环境：

condauv (仅 PyTorch >= 2.10)

conda create -y -n lerobot python=3.12

uv python install 3.12
uv venv --python 3.12

然后激活您的虚拟环境，每次打开 shell 使用 lerobot 时都需要执行此操作：

condauv (仅 PyTorch >= 2.10)

conda activate lerobot

[!NOTE] 在 WSL（Windows Subsystem for Linux）中安装 LeRobot 时，请确保也安装 evdev：
conda install evdev -c conda-forge

# Linux/macOS
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\activate

[!NOTE] 在 WSL（Windows Subsystem for Linux）中安装 LeRobot 时，请确保也安装 evdev：
sudo apt install libevdev-dev
uv pip install evdev

安装 `ffmpeg`（用于视频解码）

LeRobot 默认使用 TorchCodec 进行视频解码，这需要 ffmpeg。

[!NOTE] 平台支持： TorchCodec 不可用于 macOS Intel (x86_64)、Linux ARM (aarch64, arm64, armv7l) 或 PyTorch < 2.8 的 Windows。在这些平台上，LeRobot 会自动回退到 pyav——因此您不需要安装 ffmpeg，可以跳到步骤 3。

如果您的平台支持 TorchCodec，请使用以下方法之一安装 ffmpeg：

conda (任何 PyTorch 版本)uv (仅 PyTorch >= 2.10)

在您的 conda 环境中安装 ffmpeg。这适用于所有 PyTorch 版本，并且PyTorch < 2.10 必需：

conda install ffmpeg -c conda-forge

[!TIP] 这通常会安装带有 libsvtav1 编码器的 ffmpeg 8.X。如果遇到问题（例如 libsvtav1 缺失——使用 ffmpeg -encoders 检查——或与 torchcodec 的版本不匹配），您可以使用以下命令显式安装 ffmpeg 7.1.1：
conda install ffmpeg=7.1.1 -c conda-forge

从 PyTorch >= 2.10（TorchCodec ≥ 0.10）开始，TorchCodec 可以动态链接到系统范围的 ffmpeg 安装。这在使用 uv 或其他非 conda 环境管理器时很有用：

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

[!IMPORTANT] 系统范围的 ffmpeg 仅支持 PyTorch >= 2.10（TorchCodec ≥ 0.10）。对于较旧的 PyTorch 版本，您必须使用 conda install ffmpeg -c conda-forge。

步骤 3：安装 LeRobot 🤗

基础 lerobot 安装有意设计为轻量级——它仅包含核心 ML 依赖项（PyTorch、torchvision、numpy、opencv、einops、draccus、huggingface-hub、gymnasium、safetensors）。较重的依赖项通过可选的额外包进行管理，因此您只需安装所需的内容。

从源代码安装

首先，克隆仓库并进入目录：

git clone https://github.com/huggingface/lerobot.git
cd lerobot

然后，以可编辑模式安装库。如果您计划为代码做贡献，这很有用。

condauv

pip install -e ".[core_scripts]"  # 用于机器人工作流（录制、回放、校准）
pip install -e ".[training]"      # 用于训练策略
pip install -e ".[all]"           # 所有内容（所有策略、环境、硬件、开发工具）

uv pip install -e ".[core_scripts]"  # 用于机器人工作流（录制、回放、校准）
uv pip install -e ".[training]"      # 用于训练策略
uv pip install -e ".[all]"           # 所有内容（所有策略、环境、硬件、开发工具）

从 PyPI 安装

核心库： 使用以下命令安装基础包：

condauv

pip install lerobot

uv pip install lerobot

这仅安装核心 ML 依赖项。对于大多数工作流，您需要添加额外包。

功能额外包： LeRobot 提供功能范围的额外包，映射到常见工作流。如果您使用 uv，请在下面的命令中将 pip install 替换为 uv pip install。

额外包	添加的内容	典型用例
`dataset`	`datasets`, `av`, `torchcodec`, `jsonlines`	加载和创建数据集
`training`	`dataset` + `accelerate`, `wandb`	训练策略
`hardware`	`pynput`, `pyserial`, `deepdiff`	连接到真实机器人
`viz`	`rerun-sdk`	录制/评估期间的可视化

组合额外包为常见的 CLI 脚本组合功能额外包：

额外包	包含	典型用例
`core_scripts`	`dataset` + `hardware` + `viz`	`lerobot-record`, `lerobot-replay`, `lerobot-calibrate`
`evaluation`	`av`	`lerobot-eval`（根据需要添加策略 + 环境额外包）
`dataset_viz`	`dataset` + `viz`	`lerobot-dataset-viz`, `lerobot-imgtransform-viz`

pip install 'lerobot[core_scripts]'          # 录制、回放、校准
pip install 'lerobot[training]'              # 训练策略
pip install 'lerobot[core_scripts,training]' # 录制 + 训练
pip install 'lerobot[all]'                   # 所有内容

策略、环境和硬件额外包仍可用于特定依赖项：

pip install 'lerobot[pi]'             # Pi0/Pi0.5/Pi0-FAST 策略依赖
pip install 'lerobot[smolvla]'        # SmolVLA 策略依赖
pip install 'lerobot[diffusion]'      # Diffusion 策略依赖 (diffusers)
pip install 'lerobot[aloha,pusht]'    # 模拟环境
pip install 'lerobot[feetech]'        # Feetech 电机支持

可以组合多个额外包（例如 .[core_scripts,pi,pusht]）。有关可用额外包的完整列表，请参阅 pyproject.toml。

PyTorch CUDA 变体（仅 Linux）

在 Linux 上，安装路径决定您获得哪个 CUDA wheel。macOS 和 Windows 安装使用 PyPI 默认值（分别为 MPS / CPU / CUDA-Windows wheel），可以跳过本节。

uv-sourcepip-conda

通过 uv 从源代码安装（uv sync 或 uv pip install -e .）

torch 和 torchvision 由项目固定到 CUDA 12.8 PyTorch 索引（https://download.pytorch.org/whl/cu128，驱动程序下限 570.86）——涵盖 Ampere/Ada/Hopper/Blackwell GPU。对于典型的 NVIDIA 设置，无需操作。

要覆盖为不同的 CUDA 变体：

uv pip install --force-reinstall torch torchvision \
    --index-url https://download.pytorch.org/whl/cu126   # 较旧的驱动程序；或 cu130 用于驱动程序 ≥ 580 的 Blackwell

通过 pip/conda 从源代码安装，或从 PyPI pip install lerobot

PyPI 默认 torch wheel 目前是 cu130 捆绑的 Linux wheel，驱动程序下限 580.65。

要选择特定的 CUDA 变体：

使用 pip 或 conda — 首先使用显式索引安装 torch，然后安装 lerobot：

pip install --index-url https://download.pytorch.org/whl/cu128 torch torchvision
pip install -e ".[all]"          # 源代码
# — 或 —
pip install lerobot              # 从 PyPI

使用 uv 从 PyPI 安装 — 通过 --torch-backend 一行命令（uv ≥ 0.6）：

uv pip install --torch-backend cu128 lerobot

支持的值包括 auto、cpu、cu126、cu128、cu129、cu130，以及各种 rocm* 和 xpu。根据您的驱动程序需要进行交换。

故障排除

如果遇到构建错误，您可能需要安装额外的系统依赖项：cmake、build-essential 和 ffmpeg libs。要在 Linux 上安装这些，请运行：

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

对于其他系统，请参见：编译 PyAV

可选依赖项

LeRobot 为特定功能提供可选的额外包。可以组合多个额外包（例如 .[aloha,feetech]）。有关所有可用额外包，请参阅 pyproject.toml。如果您使用 uv，请在下面的命令中将 pip install 替换为 uv pip install。

模拟

安装环境包：aloha（gym-aloha）或 pusht（gym-pusht）。这些会自动包含 dataset 额外包。

pip install -e ".[aloha]" # 或例如 "[pusht]"

电机控制

对于 Koch v1.1，安装 Dynamixel SDK；对于 SO100/SO101/Moss，安装 Feetech SDK。

pip install -e ".[feetech]" # 或例如 "[dynamixel]"

实验跟踪

Weights and Biases 包含在 training 额外包中。要使用 Weights and Biases 进行实验跟踪，请使用以下命令登录：

wandb login

如果您的机器人还没有准备好，您现在可以组装它，在左侧查找您的机器人类型。然后按照下面的链接使用 Lerobot 与您的机器人。

安装

步骤 1（仅 conda）：安装 miniforge