训练框架开源

LeRobot

Hugging Face美国

GitHub 仓库 huggingface/lerobot

类别
框架与工具 · 训练框架
开放程度
开源
发布时间
2024 年 1 月
开源协议
Apache-2.0
发布方所在地
美国

项目简介

Hugging Face 的端到端机器人学习库,基于 PyTorch,提供统一的机器人控制接口、LeRobotDataset 数据格式和 Hub 上的数据集与模型。内置 ACT、Diffusion Policy 等模仿学习策略和 π0、π0.5、GR00T、SmolVLA 等 VLA 模型;支持 SO-100、Koch、LeKiwi、宇树 G1 等硬件的采集、训练和部署,可用 LIBERO 评测。

LeRobot 安装要点

来源:huggingface.co

依据官方资料的 v0.7.0 版本整理,核验于 2026-11-06。版本更新后命令可能变化,以官方文档为准。

  1. 安装 miniforge

    用 uv 或 venv 可跳过,但要 Python 3.12 以上

    wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
    bash Miniforge3-$(uname)-$(uname -m).sh
  2. 创建并激活环境

    每次开新 shell 都要激活

    conda create -y -n lerobot python=3.12
    conda activate lerobot
  3. 安装 ffmpeg

    缺 libsvtav1 时改装 ffmpeg=7.1.1

    conda install ffmpeg -c conda-forge
  4. 克隆仓库

    git clone https://github.com/huggingface/lerobot.git
    cd lerobot
  5. 安装 LeRobot

    录制用 core_scripts;也可 pip install lerobot

    pip install -e ".[training]"

环境要求

来源:huggingface.co
Python
>= 3.12
macOS来源:installation.mdx
Apple Silicon 需 macOS 14+,MPS 加速需 macOS 15+
NVIDIA 驱动来源:installation.mdx
Linux 默认 wheel 是 CUDA 13 版,驱动要 580.65 以上
CUDA 12 驱动
从 cu126 索引装 torch,最高到 torch 2.14
PyTorch来源:pyproject.toml
>= 2.7,< 2.16
FFmpeg来源:installation.mdx
TorchCodec 解码需要;PyTorch < 2.10 必须用 conda 装
训练显存来源:huggingface.co
按策略约 2–40 GB(batch 8),见官方算力指南和下方矩阵

适配矩阵

来源:huggingface.co

各策略组的训练峰值显存(batch 8、AdamW),官方称是粗略估算,未给推理显存

名称训练峰值显存起步 GPU
Light BC(act、vqbet、tdmpc)笔记本 GPU 即可,也可用 L4、A10G~2–6GBRTX 3060
Diffusion(diffusion、multi_task_dit)也可用 L4、A10G~8–14GBRTX 4070+
Small VLA(smolvla)也可用 L4、A10G~10–16GBRTX 4080+
Large VLA(pi0、pi0_fast、pi05、xvla、wall_x)24 GB 在 batch 1 时吃紧~24–40GBA100 40 GB+
Multimodal(groot、eo1)~24–40GBA100 40 GB+

常见报错

解法来自官方文档、维护者回复或提问者确认,部分报错出自旧版本。

Unknown encoder 'libsvtav1'

原因ffmpeg 没带 libsvtav1 编码器

解决用 ffmpeg -encoders 检查,缺的话在 conda 环境里指定装 ffmpeg 7.1.1

conda install ffmpeg=7.1.1 -c conda-forge
来源:installation.mdx
RuntimeError: Could not load libtorchcodec

原因TorchCodec 需要 ffmpeg,环境里没有可用的版本

解决PyTorch < 2.10 用 conda 装 ffmpeg;PyTorch >= 2.10 也可用系统 ffmpeg

conda install ffmpeg -c conda-forge
来源:Issue #964
OSError: libavutil.so.56: cannot open shared object file: No such file or directory

原因提问者环境里 torch 2.8 配的是 torchcodec 0.14

解决重装与 torch 匹配的 torchcodec,提问者在 torch 2.8 上装 0.7 后解决

pip install torchcodec==0.7
来源:Issue #3976
ERROR: Failed building wheel for av

原因缺编译依赖

解决安装 cmake、build-essential 和 ffmpeg 开发库后重试

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
来源:huggingface.co
ModuleNotFoundError: No module named 'libero'

原因macOS 和 Windows 上 lerobot[libero] 不会装 hf-libero

解决LIBERO 只支持 Linux,换到 Linux 环境安装

来源:installation.mdx

适配机器人

  • SO100
  • LeKiwi
  • Koch
  • HopeJR
  • Reachy2
  • OpenARM
  • Unitree G1
  • EarthRover

获取方式

相关概念

数据来源

本页信息均整理自以下公开资料。

9 条来源核验于 2026-10-01

星标、下载量等指标定期自动更新。

LeRobot:安装步骤、环境要求与常见报错 | 具身集