跳到主要内容

安装 LeRobot

本文以 LeRobot v0.5.0 为准。该版本的 pyproject.toml 声明：

  • Python 版本：>=3.12
  • 包版本：lerobot==0.5.0
  • 训练入口：安装后使用 lerobot-train
  • 可视化入口：lerobot-dataset-viz
  • 数据与机器人相关入口：lerobot-record、lerobot-replay、lerobot-info 等

面向用户的训练命令统一写成安装后的 lerobot-train。

推荐路径​

如果你只是要训练模型，优先使用艾欧智能已经构建并公开发布的 GPU 镜像。ioaitech/lerobot-gpu:v0.5.0 包含 LeRobot v0.5.0、GPU 训练依赖、视频解码依赖和 lerobot-train 命令：

docker run --rm -it --gpus all --shm-size 16g \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/outputs \
  ioaitech/lerobot-gpu:v0.5.0 \
  bash

进入容器后检查：

lerobot-info
lerobot-train --help

中国大陆环境可使用华为云同步镜像：

docker run --rm -it --gpus all --shm-size 16g \
  -v /path/to/lerobot_dataset:/data/input \
  -v /path/to/output:/outputs \
  swr.cn-east-3.myhuaweicloud.com/ioaitech/lerobot-gpu:v0.5.0 \
  bash

本地源码安装​

本地安装适合需要修改 LeRobot 源码、调试策略配置或接入自定义机器人接口的读者。

1. 准备系统依赖​

Ubuntu/Debian 可先安装基础依赖：

sudo apt-get update
sudo apt-get install -y \
  git git-lfs curl build-essential cmake pkg-config ninja-build \
  ffmpeg python3-dev \
  libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev \
  libswscale-dev libswresample-dev libavfilter-dev

国内服务器可临时改用清华 apt 源。以下示例以 Ubuntu 22.04 jammy 为例，执行前请确认发行版代号：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo sed -i 's|http://.*archive.ubuntu.com/ubuntu/|https://mirrors.tuna.tsinghua.edu.cn/ubuntu/|g' /etc/apt/sources.list
sudo sed -i 's|http://.*security.ubuntu.com/ubuntu/|https://mirrors.tuna.tsinghua.edu.cn/ubuntu/|g' /etc/apt/sources.list
sudo apt-get update

如果你的系统源文件使用新的 .sources 格式，请按清华镜像站说明修改对应文件，不要盲目覆盖。

2. 创建 Python 3.12 环境​

推荐使用 conda 或 uv。下面给出 venv 方式，便于最小复现：

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip setuptools wheel

如果系统没有 Python 3.12，可使用 conda：

conda create -y -n lerobot python=3.12
conda activate lerobot

3. 配置 pip 清华源​

临时使用：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple some-package

长期使用：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

若遇到 PyTorch CUDA wheel 下载问题，优先使用 PyTorch 官方源安装对应 CUDA 版本，再安装 LeRobot。

4. 安装 LeRobot v0.5.0​

从官方 tag 安装：

git clone https://github.com/huggingface/lerobot.git
cd lerobot
git checkout v0.5.0

pip install -e .

如果要训练 SmolVLA：

pip install -e ".[smolvla]"

如果希望一次安装大部分功能：

pip install -e ".[all]"

v0.5.0 的可选依赖中，smolvla 会安装 transformers、num2words、accelerate、safetensors 等训练所需组件；all 会包含更多机器人、仿真、策略和开发依赖，安装时间更长。

5. 验证安装​

lerobot-info
lerobot-train --help
lerobot-dataset-viz --help

能看到帮助信息后，再运行训练命令。不要在依赖未确认前直接启动长训练。

常见问题​

为什么要求 Python 3.12​

LeRobot v0.5.0 的 pyproject.toml 声明 requires-python = ">=3.12"。如果使用 Python 3.10/3.11，依赖解析或运行时行为可能与该版本不一致。

ffmpeg 为什么重要​

LeRobot 数据集通常使用 MP4 视频。训练和可视化都可能触发视频解码。官方安装文档要求准备 ffmpeg，源码安装时应先确认：

ffmpeg -version

应该用 --policy.type 还是 --policy.path​

从零训练某类策略时使用 --policy.type=act、--policy.type=diffusion 等；从已有预训练权重微调时使用 --policy.path=lerobot/smolvla_base 这类路径。SmolVLA 官方微调文档使用 --policy.path=lerobot/smolvla_base。

参考链接​