安装

本指南使用 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 创建虚拟环境：

conda create -y -n lerobot python=3.12

然后激活你的虚拟环境，每次打开 shell 使用 lerobot 时都需要这样做：

conda activate lerobot

安装 ffmpeg （用于视频解码）

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

平台支持： TorchCodec 在 macOS Intel (x86_64)、Linux ARM (aarch64、arm64、armv7l) 或 Windows 搭配 PyTorch < 2.8 上不可用。在这些平台上，LeRobot 会自动回退到 pyav —— 因此你无需安装 ffmpeg，可以跳到步骤 3。

Jetson (aarch64 + CUDA)： 上面的 pyav 回退意味着默认没有 GPU 加速的视频解码。docker/Dockerfile.jetson 针对 JetPack 6.2 从源码构建了支持 CUDA 的 torch/torchcodec —— 由社区维护，预构建镜像见 ravediamond/lerobot-jetson，背景见 issue #819。

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

conda install ffmpeg -c conda-forge

步骤 3：安装 LeRobot 🤗

基础的 lerobot 安装有意保持轻量 —— 它只包含核心 ML 依赖（PyTorch、torchvision、numpy、opencv、einops、draccus、huggingface-hub、gymnasium、safetensors）。较重的依赖被放在可选 extra 之后，因此你只需安装自己需要的部分。

从源码安装

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

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

然后，以可编辑模式安装该库。如果你打算为代码做贡献，这会很有用。

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)

从 PyPI 安装

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

pip install lerobot

这只会安装核心 ML 依赖。对于大多数工作流，你还需要添加 extra。

功能 Extra： LeRobot 提供映射到常见工作流的按功能划分的 extra。如果你使用 uv，请将下面命令中的 pip install 替换为 uv pip install。

复合 Extra 为常见 CLI 脚本组合功能 extra：

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、环境和硬件 extra 仍可用于特定依赖：

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

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

PyTorch CUDA 变体（仅限 Linux）

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

uv pip install --force-reinstall torch torchvision \
    --index-url https://download.pytorch.org/whl/cu126   # older drivers; or cu130 for Blackwell on driver ≥ 580

故障排查

如果遇到构建错误，你可能需要安装额外的系统依赖：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 为特定功能提供可选 extra。可以组合多个 extra（例如 .[aloha,feetech]）。有关所有可用 extra，请参阅 pyproject.toml。如果你使用 uv，请将下面命令中的 pip install 替换为 uv pip install。

simulation

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

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

电机控制

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

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

实验跟踪

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

wandb login

如果你的机器人尚未准备好，现在可以组装它，在左侧查找你的机器人类型。然后按照下面的链接在你的机器人上使用 LeRobot。