- 类别
- 框架与工具 · 训练框架
- 开放程度
- 开源
- 发布时间
- 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。版本更新后命令可能变化,以官方文档为准。
安装 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创建并激活环境
每次开新 shell 都要激活
conda create -y -n lerobot python=3.12 conda activate lerobot安装 ffmpeg
缺 libsvtav1 时改装 ffmpeg=7.1.1
conda install ffmpeg -c conda-forge克隆仓库
git clone https://github.com/huggingface/lerobot.git cd lerobot安装 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–6GB | RTX 3060 |
| Diffusion(diffusion、multi_task_dit)也可用 L4、A10G | ~8–14GB | RTX 4070+ |
| Small VLA(smolvla)也可用 L4、A10G | ~10–16GB | RTX 4080+ |
| Large VLA(pi0、pi0_fast、pi05、xvla、wall_x)24 GB 在 batch 1 时吃紧 | ~24–40GB | A100 40 GB+ |
| Multimodal(groot、eo1) | ~24–40GB | A100 40 GB+ |
常见报错
解法来自官方文档、维护者回复或提问者确认,部分报错出自旧版本。
Unknown encoder 'libsvtav1'原因ffmpeg 没带 libsvtav1 编码器
解决用 ffmpeg -encoders 检查,缺的话在 conda 环境里指定装 ffmpeg 7.1.1
来源:installation.mdxconda install ffmpeg=7.1.1 -c conda-forgeRuntimeError: Could not load libtorchcodec原因TorchCodec 需要 ffmpeg,环境里没有可用的版本
解决PyTorch < 2.10 用 conda 装 ffmpeg;PyTorch >= 2.10 也可用系统 ffmpeg
来源:Issue #964conda install ffmpeg -c conda-forgeOSError: 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 后解决
来源:Issue #3976pip install torchcodec==0.7ERROR: Failed building wheel for av原因缺编译依赖
解决安装 cmake、build-essential 和 ffmpeg 开发库后重试
来源:huggingface.cosudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-devModuleNotFoundError: No module named 'libero'原因macOS 和 Windows 上 lerobot[libero] 不会装 hf-libero
解决LIBERO 只支持 Linux,换到 Linux 环境安装
来源:installation.mdx
适配机器人
- SO100
- LeKiwi
- Koch
- HopeJR
- Reachy2
- OpenARM
- Unitree G1
- EarthRover