Ubuntu 和 macOS 都能一次装好 LeRobot，怎么做？6 步跨平台部署实战

Ubuntu 和 macOS 都能一次装好 LeRobot，怎么做？6 步跨平台部署实战

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot

LeRobot 是基于 PyTorch 的端到端机器人学习框架，覆盖数据采集、策略训练到机器人控制。从一台裸的 Ubuntu 或 macOS 机器到 LeRobot 跨平台部署跑通，只需要 6 步，跟着走就能得到一台能训练策略、能接硬件的机器。

一、先把根因拆了：两个系统的差异到底在哪

在 Ubuntu 和 macOS 上做 LeRobot 部署，报错经常长得完全不一样，因为底层差了三件事。

第一件是系统库栈。视频解码两端都依赖系统里的 ffmpeg，但 Ubuntu 走 apt，macOS 走 Homebrew，装法和库路径都不一样。第二件是 C 工具链：Ubuntu 用 build-essential 拿到 gcc 套件，macOS 依赖 Xcode Command Line Tools 里的 clang。凡是 C 扩展包（比如 PyAV）编译失败，根子基本都在这。

第三件是硬件驱动的 wheel 分发。最典型的是 RealSense 相机：官方 SDK 按平台发不同的 wheel，Linux 装 pyrealsense2，macOS 装 pyrealsense2-macosx。这个差异 pyproject.toml 里已经用平台标记处理好了，会自动选对轮子，你只管装一次。

还有一个高频误区：以为 Python 3.10 够用。项目现在要求 ≥3.12，照着老教程建 3.10 环境，装的时候依赖解析直接失败。

二、一条主线走通：从裸机到能 import 🚀

下面是单条主线，两个系统只在括号里注明差异，不用来回翻。

[!TIP] 每开一个新终端先conda activate lerobot。忘了激活环境，是"明明装好了却报 ImportError"的第一大来源。

2.1 环境体检：先确认两个数字

目的：动手前确认宿主机的 Python 版本和 ffmpeg 是否已就位，避免装到一半返工。

跑体检命令：

python --version # 期望 3.12 及以上；若是 3.10 需先升级 ffmpeg -version # 报错说明没装，下一步会补上

看到版本号就算通过。ffmpeg 暂时没有没关系，2.3 会处理。

2.2 建隔离环境：别污染系统 Python

目的：把 LeRobot 关进独立环境，防止它和系统里其他项目抢 torch、numpy 版本。

创建并激活（用 uv 的同学换成uv venv --python 3.12，后面命令把 pip 换成uv pip即可）：

conda create -y -n lerobot python=3.12 conda activate lerobot conda install ffmpeg -c conda-forge # 或 apt（Ubuntu）/ brew（macOS）装 ffmpeg

提示符前出现(lerobot)就说明环境生效了。conda-forge 的 ffmpeg 连编码器都齐全，省掉系统库路径的麻烦。

2.3 系统依赖：编译工具链一次装齐

目的：把 torchcodec 不可用时回退到 PyAV 的编译场景也覆盖掉，不让系统库卡住安装。

Ubuntu 一条 apt 命令全装齐（macOS 对应brew install cmake pkg-config ffmpeg，另需 Xcode CLT）：

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

apt 提示安装完成、无报错即成功；macOS 侧brew install结束且ffmpeg -version有输出就算过。

2.4 editable 模式装项目

目的：代码直接指向源码树，改完不用重装，同时把核心依赖解析落盘。

克隆并按工作流选 extras 安装（两个系统命令完全相同）：

git clone https://gitcode.com/GitHub_Trending/le/lerobot cd lerobot pip install -e ".[core_scripts,training]" # 采集+训练；想全量用 .[all]

结尾看到Successfully installed lerobot-0.6.2说明这一步成了。

2.5 首次运行：确认 CLI 与版本

目的：验证入口点注册正常、版本号正确，为后面的训练和采集打底。

跑通确认：

python -c "import lerobot; print(lerobot.__version__)" # 期望 0.6.2 lerobot-find-port # 无硬件也能执行，确认 CLI 可用

看到版本号 0.6.2 输出，主线就走完了。

三、提速与按需裁剪：3 个真正有用的招

3.1 并行编译

场景：.[all]会构建一批 C 扩展，默认单核跑很慢。

export MAKEFLAGS="-j$(nproc)" && pip install -e ".[all]"

效果：编译耗时随核心数明显下降，大 extras 尤其实感。

3.2 extras 按需装

场景：只训练策略、不碰硬件，却装了 hardware 全家桶。一条pip install -e ".[training]"替代.[all]。效果：依赖树小一圈，版本冲突面同步缩小。

3.3 缓存复用

场景：反复重建环境或重装，同一个 wheel 被重复下载、重复编译。

pip install --cache-dir ~/.pipcache -e ".[training]"

效果：第二次安装起跳过下载与构建，几分钟变几十秒。

四、硬件对接

4.1 电机

两套 SDK 覆盖主流舵机，按品牌装一行 extras（对应实现在 src/lerobot/motors/）：

pip install -e ".[feetech]" # SO100/SO101 等 Feetech 舵机 pip install -e ".[dynamixel]" # Koch 等 Dynamixel 舵机

4.2 相机

RealSense 深度相机一个 extras，wheel 按平台自动切换（抽象层在 src/lerobot/cameras/）：

pip install -e ".[intelrealsense]" # macOS 上自动落到 pyrealsense2-macosx

装完插上设备，跑lerobot-find-cameras和lerobot-find-port确认枚举到了再进下一步。

五、排错速查

• numpy 与 torch 版本冲突→ 根因是环境里残留旧版 numpy，pip install "numpy>=2.0,<2.3"拉回项目区间。
• PyAV 编译失败→ 根因是 Ubuntu 缺 libav* 开发库，按 2.3 那条 apt 命令补装；macOS 执行brew install ffmpeg。
• 改了配置 CMake 不生效→ 根因是构建目录缓存脏了，删掉build/与CMakeCache.txt后重新cmake .。
• 电机/相机枚举不到→ 重新插拔设备，跑lerobot-find-cameras看输出，端口识别不到多半是权限问题。

六、验证与收尾

两条命令收尾：

python -c "import lerobot; print(lerobot.__version__)" # 期望 0.6.2 lerobot-info # 看 CUDA 支持行

看到版本 0.6.2 说明基础功能就位；有 NVIDIA 显卡的话，lerobot-info会打印 CUDA 版本和 GPU 型号，后续训练日志里也能看到 CUDA 加速信息。

LeRobot 的跨平台支持还在持续迭代，Windows 目前是实验性支持，社区也在压缩首次配置时间、推进一键安装脚本。遇到本文没覆盖的问题，直接去项目 Issue 系统反馈，或按 CONTRIBUTING.md 参与贡献。

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot