{{htmlmetatags>metatag-robots=(index,follow)
metatag-keywords=(LeRobot,安装,PyPI,conda,uv,Docker,Python 3.12)
metatag-description=(LeRobot 安装指南：支持 PyPI、源码、conda、uv 和 Docker 多种安装方式，以及可选依赖组管理)
}}

====== LeRobot 安装与设置 ======

本文档提供 LeRobot 框架的技术安装说明，涵盖环境搭建、依赖管理和可选功能安装。

[[机器人:lerobot:home|返回概述]]

===== 安装方法概览 =====

LeRobot 可以通过 PyPI 或源码安装。包使用 **可选扩展系统**（在 ''pyproject.toml'' 中定义）来最小化核心安装的体积，同时支持庞大的硬件、仿真环境和策略架构生态。

===== 环境要求 =====

==== Python 版本 ====

LeRobot 需要 **Python >= 3.12**。同时明确声明支持 Python 3.13。

==== 系统依赖 ====

  * **FFmpeg**：对 ''LeRobotDataset'' 中的视频解码至关重要。框架默认使用 ''TorchCodec''，需要 ''ffmpeg'' 头文件和二进制文件
  * **平台特定驱动**：真实机器人交互通常需要串口通信（''pyserial''）或 USB 访问（''libusb''）

===== 环境搭建 =====

==== Conda（推荐通用使用） ====

推荐使用 ''miniforge'' 以确保一致的依赖解析：

<code>
conda create -y -n lerobot python=3.12
conda activate lerobot
</code>

如果在 Windows Subsystem for Linux（WSL）内安装，必须通过 conda-forge 安装 ''evdev''（用于硬件控制的 ''pynput'' 所需）。

==== UV（推荐性能/Docker 场景） ====

''uv'' 用于项目的快速环境实例化：

<code>
uv venv
uv pip install lerobot[all]
</code>

**重要**：仅在 **PyTorch >= 2.10**（TorchCodec >= 0.10）时支持系统级 ''ffmpeg''（通过 ''apt'' 或 ''brew''）。

===== 安装步骤 =====

==== 从 PyPI 安装 ====

基础包仅包含轻量级核心 ML 依赖：

<code>
pip install lerobot
</code>

==== 从源码安装（可编辑模式） ====

推荐研究人员和贡献者使用，可立即测试本地更改：

<code>
git clone https://github.com/huggingface/lerobot
cd lerobot
pip install -e ".[all]"
</code>

===== 可选依赖组 =====

LeRobot 使用多层扩展系统管理其庞大的依赖树。

==== 功能级扩展 ====

^ 扩展名 ^ 包含包 ^ 用途 ^
| ''[dataset]'' | datasets, av, torchcodec, jsonlines | 核心数据加载和 v3 格式支持 |
| ''[training]'' | [dataset], accelerate, wandb | 策略训练和实验跟踪 |
| ''[hardware]'' | pynput, pyserial, deepdiff | 真实机器人和遥操作控制 |
| ''[viz]'' | rerun-sdk | 通过 Rerun 实时可视化 |

==== 组合扩展 ====

^ 扩展名 ^ 用途 ^ CLI 命令 ^
| ''[core_scripts]'' | 标准机器人工作流 | lerobot-record, lerobot-replay, lerobot-calibrate |
| ''[evaluation]'' | 策略评估 | lerobot-eval |
| ''[dataset_viz]'' | 数据集探索 | lerobot-dataset-viz, lerobot-imgtransform-viz |

===== 策略和仿真扩展 ====

许多策略架构和仿真环境需要第三方 SDK，需单独安装以避免版本冲突：

  * **Pi0 / Pi0.5**：''pip install "lerobot[pi]"''
  * **SmolVLA**：''pip install "lerobot[smolvla]"''

===== 视频解码：TorchCodec 和 FFmpeg ====

LeRobot 利用 ''TorchCodec'' 实现高效的多线程视频解码。

**TorchCodec 兼容性**：

  * **支持**：Linux (x86_64)、macOS (Apple Silicon)、Windows（PyTorch >= 2.8）
  * **不支持**：Linux ARM (aarch64)、macOS Intel (x86_64)
  * **回退**：在不支持的平台上，系统自动回退到 ''pyav''

''libsvtav1'' 编码器是 ''LeRobotDataset'' 格式的首选编解码器。

===== Docker 安装 =====

LeRobot 提供多种 Docker 配置：

  * **Dockerfile.user**：基于 Python Slim，适用于一般实验
  * **Dockerfile.internal**：用于 Hugging Face 内部 CI，包含 NVIDIA CUDA 支持
  * **Dockerfile.benchmark.robotwin**：RoboTwin 2.0 集成测试专用镜像

===== 相关页面 =====

  * [[机器人:lerobot:home|LeRobot 框架概述]]
  * [[机器人:lerobot:核心概念|核心概念]]
  * [[机器人:lerobot:命令行界面|命令行界面]]