3条命令完成LeRobot部署：Ubuntu与macOS安装、相机电机对接及排错清单

3条命令完成LeRobot部署Ubuntu与macOS安装、相机电机对接及排错清单【免费下载链接】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-train这一步解决一台没装过本项目的电脑如何装到能运行命令行工具。先说结论只需要管两件事——Python 版本和 ffmpeg其余交给 pip。LeRobot 的 pyproject.toml 里硬性要求requires-python 3.12低于 3.12 的系统 Python 直接建环境时就跳过别再纠结 3.10。步骤Ubuntu 做法macOS 做法为什么不同建 Python 环境conda create -y -n lerobot python3.12同左环境管理本身无平台差异3.12 是硬依赖装 ffmpegconda install ffmpeg -c conda-forge同左装进 conda 环境可避免与系统库版本打架备用系统构建库sudo apt-get install cmake build-essential python3-dev pkg-configbrew install cmake pkg-configUbuntu 的 C 库走 aptmacOS 走 Homebrew包源体系不同建环境并在其中安装视频解码依赖这条命令在干什么创建隔离的 3.12 环境再把 ffmpeg 装进环境而不是系统防止污染conda create -y -n lerobot python3.12 conda activate lerobot conda install ffmpeg -c conda-forge装包时按工作流选 extras而不是无脑全装。基础包只含 torch、opencv、numpy 等核心 ML 依赖重功能全部藏在可选项里# 记录/回放/校准机器人的工作流依赖 pip install lerobot[core_scripts] # 要训练策略再加 pip install lerobot[training]需要改源码的开发者先克隆仓库再 editable 安装改代码不用重装git clone https://gitcode.com/GitHub_Trending/le/lerobot cd lerobot pip install -e .[core_scripts][!TIP] 完整 extras 清单见 pyproject.tomldataset、training、hardware、viz、evaluation、dataset_viz等可组合如lerobot[core_scripts,feetech]。lerobot[all]会拉下全部策略与硬件依赖首次安装不建议。验证运行lerobot-info应看到 Python 3.12.x、PyTorch 版本、ffmpeg 版本号以及lerobot-record、lerobot-train等命令列表且 FFmpeg 一项不是 N/A。 跨系统迁移只重做三处平台相关部分从 Ubuntu 搬到 macOS或反向时lerobot 包本身是平台无关的但有三处必须在新系统上重来。平台差异点UbuntumacOS为什么不同视频解码器用 torchcodec 链接 conda ffmpegApple Silicon 用 torchcodecIntel Mac 无预编译轮子自动回退 pyav 解码torchcodec 未发布 darwin x86_64 轮子Linux ARM 同理RealSense 相机包pyrealsense2pyrealsense2-macosxRealSense SDK 分平台构建由intelrealsenseextra 按系统自动选型输入设备依赖WSL 下需补装evdevconda install evdev -c conda-forge无此问题evdev 只能读 Linux 输入子系统WSL 缺底层库相机驱动这条命令在干什么按当前系统自动挑选正确的 RealSense 包不用手动区分平台pip install lerobot[intelrealsense][!WARNING] macOS 上使用 Intel RealSense 官方标注为不稳定若报failed to set power state用sudo重跑检测命令可解决。[!TIP] 迁移正确姿势在新系统用同样的 extras 重建 conda 环境重装一次不要复制site-packages目录二进制依赖torch、torchcodec 等跨平台不通用。验证python -c import lerobot; print(ok)无报错lerobot-info显示的 Python、PyTorch 版本与旧环境一致。 旧环境损坏修复三种高频报错定位环境出问题大多是下面三类先按报错关键字对号入座。pip 编译阶段卡住或 CMake 报错现象安装长时间编译后报 CMake 或找不到 FFmpeg 库。根因是系统构建库缺失安装文档 installation.mdx 的 Troubleshooting 一节给的方案如下# Ubuntu 一把补齐 CMake、GCC 与 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-devmacOS 对应执行brew install ffmpeg cmake pkg-config。验证重新跑pip install lerobot[core_scripts]不再进入源码编译阶段正常应全部命中预编译轮子。视频解码失败或 ffmpeg 版本不匹配现象加载含 MP4 的数据集时抛异常或 torchcodec 报libsvtav1缺失。根因conda-forge 现在默认装 ffmpeg 8.x带 libsvtav1 编码器与部分 torchcodec 版本不兼容。降级到稳定版即可conda install ffmpeg7.1.1 -c conda-forge验证ffmpeg -version首行显示 7.1.1import torchcodec无报错。GPU 不可用CUDA 版本与驱动对不上现象torch.cuda.is_available()返回False。根因Linux 上安装路径决定你拿到哪个 CUDA 变体——uv 源码安装默认 cu128驱动下限 570.86PyPI 安装则是 cu130 捆绑轮子驱动下限 580.65驱动偏旧就加载失败。修复命令在干什么显式指定 cu128 后端重装 lerobot 及其 torchuv pip install --torch-backend cu128 lerobotpip 用户改用--index-url指定 cu128 索引先装 torch 再装 lerobot具体写法见 installation.mdx 的 CUDA 小节MPS/Intel XPU 的验证方法见 torch_accelerators.mdx。验证python -c import torch; print(torch.cuda.is_available())输出True。 相机与电机端口快速定位环境通了但硬件看不见是第二大坑。LeRobot 自带两个探测工具源码在 src/lerobot/scripts/。相机枚举列出所有 USB/网络摄像头及各自的 Id、分辨率、帧率拿到 Id 才能配置lerobot-find-cameras opencv # 只枚举 Intel RealSense lerobot-find-cameras realsense输出形如--- Detected Cameras ---每个设备一段。若提示pyrealsense2 library not found说明上文的intelrealsenseextra 没装。[!TIP] 设备 Id 在重启或重新插拔后可能变化配置机器人时以当场lerobot-find-cameras的输出为准。该脚本默认还会抓帧存到outputs/captured_images/看到新图片说明取流成功。电机串口定位这条命令在干什么记录插拔 USB 前后的/dev/tty*差集精确定位电机总线端口lerobot-find-port # 按提示拔掉 USB 线缆再回车输出类似 /dev/ttyUSB0Windows 为 COM 口拿到端口号后按电机品牌装对应 SDKpip install lerobot[feetech]SO-100/SO-101或pip install lerobot[dynamixel]Koch驱动实现位于 src/lerobot/motors/。验证lerobot-find-port明确打印出端口号且对应 extra 的 SDK 能import成功。✅ 部署结果一次性验证正式干活前跑一遍下面三步把整条链路环境→解码→训练打通。第一步打印系统摘要确认 Python、PyTorch、ffmpeg、GPU 全在表里lerobot-info python -c import torch; print(torch.cuda.is_available())第二步跑一个 4 步的微型训练做冒烟测试参数取自 Makefile 的官方测试目标需先装仿真 extrapip install lerobot[aloha]lerobot-train --policy.typeact --policy.dim_model64 \ --policy.n_action_steps20 --policy.chunk_size20 \ --env.typealoha --env.episode_length5 \ --dataset.repo_idlerobot/aloha_sim_transfer_cube_human \ --dataset.image_transforms.enabletrue --dataset.episodes[0] \ --batch_size2 --steps4 --wandb.enablefalse看到 loss 开始滚动、评估轮次跑完说明环境已可承接真实数据采集与完整训练。部署完成自检清单conda 环境已激活python --version是 3.12.xlerobot-info中 lerobot 与 FFmpeg 版本均非 N/Apip list包含所需 extrasdatasets、av、torchcodec 或 pyav、pynput 等有 GPUtorch.cuda.is_available()返回 TrueMPS 换mps有相机lerobot-find-cameras能列出设备并抓到样图有电机lerobot-find-port打印出端口号品牌 SDK 可导入4 步 aloha 仿真训练冒烟测试跑通任何一项不通优先回旧环境损坏修复一节排查仍卡住时把lerobot-info的完整输出附上再向项目提交 issue定位会快很多。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考