安装

本指南使用 conda（通过 miniforge）来管理环境（推荐）。如果你更倾向于使用其他环境管理器（例如 uv、venv），请确保已安装 Python >=3.12，然后直接跳转到 环境设置。

步骤 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

uv python install 3.12
uv venv --python 3.12

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

conda activate lerobot

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

平台要求

在 Apple Silicon 上，PyTorch 需要 macOS 14 或更高版本，而 MPS 加速需要 macOS 15 或更高版本（在 macOS 14 上，LeRobot 会回退到 CPU）。在 Linux 上，默认的 PyTorch 轮子需要 580.65 或更高版本 的 NVIDIA 驱动程序；对于较旧的驱动程序，请参阅 PyTorch CUDA 变体。

安装 ffmpeg（用于视频解码）

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

平台支持：TorchCodec 在 macOS Intel (x86_64) 或 Linux armv7l 上不可用。在这些平台上，LeRobot 会自动回退到 pyav——因此您无需安装 ffmpeg，可以直接跳到第 3 步。

Jetson (aarch64 + CUDA)：视频解码默认在 CPU 上运行。docker/Dockerfile.jetson 针对 JetPack 6.2 从源码构建带有 CUDA 支持的 torch/torchcodec——由社区维护，预构建镜像参见 ravediamond/lerobot-jetson，背景信息参见 #819。

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

conda install ffmpeg -c conda-forge

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS (Apple Silicon)
brew install ffmpeg

步骤 3：安装 LeRobot 🤗

基础的 lerobot 安装被刻意设计得轻量——它仅包含核心机器学习依赖项（PyTorch、torchvision、numpy、opencv、einops、draccus、huggingface-hub、gymnasium、safetensors）。较重的依赖项被置于可选的额外组件之后，以便您只需安装所需的内容。

从源代码

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

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)

uv pip install -e ".[core_scripts]"  # For robot workflows (recording, replaying, calibrate)
uv pip install -e ".[training]"      # For training policies
uv pip install -e ".[all]"           # Everything (all policies, envs, hardware, dev tools)

从 PyPI 安装

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

pip install lerobot

uv pip install lerobot

此操作仅安装核心机器学习依赖项。对于大多数工作流，您还需要添加额外的依赖项。

附加功能： LeRobot 提供了映射到常见工作流的 按功能划分的附加组件。如果您正在使用 uv，请将以下命令中的 pip install 替换为 uv pip install。

Composite Extras 为常见的 CLI 脚本组合了功能附加组件：

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

策略、环境和硬件附加组件仍可用于特定的依赖项：

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

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

PyTorch CUDA 版本（仅限 Linux）

在 Linux 上，torch 和 torchvision 来自 PyPI，其默认 wheel 为 CUDA 13 构建版本（最低驱动要求为 580.65）。macOS 和 Windows 的安装使用 PyPI 默认 wheel，可以跳过本节。

对于较旧的驱动程序或 GPU，请先从对应的 PyTorch 索引 安装 PyTorch，然后再安装 LeRobot。PyPI 上的 Linux TorchCodec 也是 CUDA 13 构建版本，因此请从 CPU 索引中获取（如果 torch 版本低于 2.11，请从 TorchCodec 兼容性表 中选择匹配的发布版本）：

pip install --index-url https://download.pytorch.org/whl/cu126 torch torchvision
pip install --index-url https://download.pytorch.org/whl/cpu torchcodec
pip install -e ".[all]"          # source
# — or —
pip install lerobot              # from PyPI

cu126 是 PyTorch 为仅支持 CUDA 12 的驱动程序保留的构建版本。torch 2.15 没有 CUDA 12 构建，因此该索引会安装 torch 2.14，而继续使用 CUDA 12 意味着必须停留在 torch 2.14 或更早版本。

使用 uv pip 时，--torch-backend 可在一步中选定索引，例如 uv pip install --torch-backend cu126 lerobot。uv sync 始终安装已提交的锁定文件：若要在此处更改 CUDA 构建，请在 pyproject.toml 的 [tool.uv.index] 和 [tool.uv.sources] 中添加该索引，然后重新运行 uv lock。

故障排除

如果遇到构建错误，您可能需要安装额外的系统依赖项：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）、libero（仅限 Linux）或 metaworld。 这些包会自动包含 dataset 附加组件。

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

电机控制

为你的电机安装相应的附加组件：Koch v1.1 使用 dynamixel，SO100/SO101/Moss 使用 feetech。两者都通过 rustypot 与电机通信。

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

实验跟踪

Trackio 包含在 training 附加组件中。本地运行无需账户或登录：它们存储在 ~/.cache/huggingface/trackio 下的本地 SQLite 数据库中。使用以下命令打开仪表板：

trackio show --project lerobot

要将运行同步到 Hugging Face Space（若不存在则自动创建），请运行 hf auth login 并传入 --trackio.space_id=<user>/<space>。启用跟踪的远程任务（--job.target）需要 space_id，因为任务结束时 pod 的本地数据库会丢失。

Space 的隐私设置默认为 None：除非组织的默认设置为私有，否则新建的 Space 均为公开。传入 --trackio.private=true 以创建私有 Space。

每次运行都会记录启动它的命令及其控制台输出（打印、日志、回溯），两者都会显示在仪表板中该运行的页面上。在 Space 上，它们的可见性与 Space 本身相同；传入 --trackio.capture_console=false 可将控制台输出排除在该运行之外。

从 Weights & Biases 迁移

后续步骤

• 有机器人吗？按照侧边栏中 Robots 下的对应页面（例如 SO-101）进行组装和校准，然后记录一个数据集，并使用 imitation learning tutorial 训练你的第一个策略。
• 还没有硬件？ 可以使用 LIBERO 在仿真环境中训练和评估策略，或者尝试 Colab notebooks。
• 想要参与贡献？请阅读贡献指南。
• 请随时备有速查表：它集中列出了所有 LeRobot 命令。