LeRobot 安装部署与排障从环境自检到验收跑通的完整流程【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobotLeRobot 是 Hugging Face 面向真实机器人的 PyTorch 库。本文沿安装时间线把部署坑位拆成三个阶段每处都配可复现命令与验证步骤读完你能完成环境自检、解决依赖冲突并用lerobot-info跑通验收。你现在卡在哪一步先对照下面的表直接跳到对应章节安装阶段典型症状跳转环境准备Python 还是 3.10/3.11装包直接被拒安装前环境自检核心依赖VersionConflict、GPU 识别不到、视频解码报错阶段二安装核心依赖可选扩展电机/相机模块缺失、仿真环境装不上阶段三可选扩展与硬件适配结果确认不知道算不算装好了验收测试安装前环境自检以下要求全部可以在仓库里找到出处pyproject.toml 声明了requires-python 3.12安装文档 给出了 ffmpeg 与 WSL 的额外条件。检查项命令通过标准Python 版本python --version3.12 或 3.13视频解码组件ffmpeg -version输出版本号macOS Intel、Linux armv7l 无 TorchCodec 轮子可跳过会自动回退 PyAVNVIDIA 驱动Linux GPU 用户nvidia-smi驱动 ≥ 570.86cu128 轮子或 ≥ 580.65PyPI 默认 cu130 轮子输入事件WSL 用户conda list evdev已安装 evdev串口可见性接硬件ls /dev/ttyUSB* /dev/ttyACM*能看到电机对应的串口设备按阶段排雷阶段一创建并激活环境Python 低于 3.12 时 pip 直接拒装现象执行pip install lerobot报ERROR: Package lerobot requires a different Python: 3.10.12 not in 3.12。原因当前版本 LeRobot 硬性要求 Python ≥3.12网上流传的 3.10 教程已经失效。解决重建环境conda create -y -n lerobot python3.12激活conda activate lerobot为什么这样改版本下限写在 pyproject.toml 的requires-python字段里升级任何依赖包都绕不开换解释器是唯一解。验证运行python --version看到Python 3.12.x即成功。WSL 下缺输入事件组件现象在 WSL 里装好后键盘/手柄等输入设备打不开或导入 evdev 失败。原因官方安装文档明确把 evdev 列为 WSL 场景的必装项。解决conda install evdev -c conda-forge。 为什么这样改evdev 依赖 Linux 输入事件接口WSL 需要单独的包才能提供对应开发头文件。验证运行python -c import evdev无任何输出即成功。阶段二安装核心依赖视频解码报错ffmpeg 缺失或 TorchCodec 平台不支持现象加载含 MP4 的 LeRobotDataset 时报 torchcodec 相关错误或lerobot-info里FFmpeg version: N/A。原因默认用 TorchCodec 解码视频它依赖 ffmpeg且部分平台没有可用轮子。解决在 conda 环境内装 ffmpegconda install ffmpeg -c conda-forge若提示libsvtav1缺失或版本与 torchcodec 不匹配钉住稳定版conda install ffmpeg7.1.1 -c conda-forge为什么这样改conda 环境内安装的 ffmpeg 兼容所有 PyTorch 版本系统级 ffmpeg 只对 TorchCodec ≥0.10PyTorch ≥2.10生效环境内安装更稳。验证运行ffmpeg -version看到版本号输出即成功。说明在 macOS Intelx86_64、Linux armv7l 等无轮子平台上项目会自动回退 PyAV 解码器可跳过此步平台支持矩阵写在 pyproject.toml 的 dataset extra 注释里。缺系统库导致编译失败现象pip install -e .在编译 av 时失败提示找不到 cmake 或 libavformat 头文件。原因PyAV 需要系统侧的 FFmpeg 开发库与构建工具链。解决按官方 Troubleshooting 一节装齐系统依赖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为什么这样改这些是 安装文档 原样给出的清单补齐后编译器才能链接 FFmpeg。验证重新运行pip install -e .[core_scripts]看到Successfully installed即成功。Linux 的 CUDA 变体与驱动对不上现象安装成功但运行时torch.cuda.is_available()返回False或加载 CUDA 库失败。原因不同安装路径对应不同 CUDA 轮子——uv 源码安装被项目钉在 cu128驱动下限 570.86而 PyPI 默认轮子是 cu130驱动下限 580.65。解决先查驱动nvidia-smi旧驱动就显式换 cu128 源重装pip install --index-url https://download.pytorch.org/whl/cu128 torch torchvision用 uv 的话可一行搞定uv pip install --torch-backend cu128 lerobot为什么这样改CUDA 轮子自带运行时轮子与驱动版本匹配后装上了却找不到 GPU才会消失。验证运行python -c import torch; print(torch.cuda.is_available())看到True即成功。源码安装需要仓库时先克隆再装git clone https://gitcode.com/GitHub_Trending/le/lerobot cd lerobot pip install -e .[core_scripts] # 机器人工作流 pip install -e .[training] # 策略训练阶段三可选扩展与硬件适配电机与相机模块缺失现象运行lerobot-find-port或lerobot-find-cameras时抛出ModuleNotFoundError: No module named serial一类错误报错信息会提示你补装对应 extra。原因基础安装刻意保持轻量串口pyserial、相机等硬件依赖放在 optional extras 后面。解决按工作流组合安装pip install -e .[core_scripts]含 dataset hardware viz按硬件精配SO100/SO101/Moss 用pip install -e .[feetech]Koch v1.1 用pip install -e .[dynamixel]RealSense 相机用pip install -e .[intelrealsense]为什么这样改extra 与 CLI 脚本、硬件型号一一对应见 pyproject.toml 的[project.optional-dependencies]只装用到的能避免解析器拖进无关大依赖。验证运行lerobot-find-port看到The port of this MotorsBus is /dev/...即成功运行lerobot-find-cameras看到相机列表即成功。Ubuntu 24.04 上 placo 加载失败现象import placo报liburdfdom_sensor.so.4.0: cannot open shared object file。原因placo 的二进制轮子链接的是 urdfdom 4.x ABI不设上限的解析器会拉进 cmeel-urdfdom 6.x 的新 soname与轮子对不上。解决按 pyproject.toml 中 kinematics extra 的钉法安装pip install placo0.9.6,0.9.16 cmeel-urdfdom4,5 cmeel-tinyxml211为什么这样改0.9.16与 cmeel 上限共同约束解析器选择旧 ABI让二进制与系统库版本对齐。验证运行python -c import placo无任何输出即成功。部分仿真环境装不成 extra现象pip install -e .[robocasa]报未知 extra或.[robomme]陷入版本冲突死胡同。原因pyproject.toml 注释里写明RoboCasa 反向钉死lerobot0.3.3使依赖图不可解RoboMME 依赖树要求numpy2与基础依赖numpy2直接冲突VLABench 根本没有 PyPI 发布。解决按各 benchmark 文档手动安装robocasa 文档、vlabench 文档或直接用官方镜像docker pull huggingface/lerobot-cpu:latest docker pull huggingface/lerobot-gpu:latest为什么这样改官方 Dockerfile 已用uv pip install --override等手段解决这些冲突复用镜像比自己修依赖更稳。验证运行docker run -it --rm huggingface/lerobot-cpu:latest lerobot-info看到版本信息输出即成功。验收测试第一层基础信息运行lerobot-info。该命令即使依赖不全也能运行见 源码会列出 LeRobot 版本、PyTorch 版本、FFmpeg 版本、CUDA 状态与已注册的lerobot-*脚本。判断标准LeRobot version一行是版本号而非N/AGPU 机器上Is PyTorch built with CUDA support?为True某行为N/A就说明对应组件缺失。第二层最小示例跑通仓库 Makefile 内置了 CI 同款端到端用例。先装仿真依赖pip install -e .[aloha,pusht]然后执行make DEVICEcpu test-act-ete-train它会在aloha仿真环境上用lerobot/aloha_sim_transfer_cube_human数据集训练 ACT 策略 4 步。判断标准进程正常结束且tests/outputs/act/checkpoints/下生成检查点目录即成功。想一次覆盖 ACT、Diffusion、TDMPC、SmolVLA 四个策略的训练评估运行make DEVICEcpu test-end-to-end见 Makefile。第三层硬件或仿真验证仿真装好pusht环境后用lerobot-eval对评估好的策略跑一个 episode看到环境画面与成功计数即通过。真机运行lerobot-find-joint-limits工具会扫描连接电机的运动范围并生成限位配置看到关节限位报告输出即通过。排障速查表错误现象可能原因快速修复requires a different Python: 3.x not in 3.12环境 Python 过旧重建环境conda create -y -n lerobot python3.12liburdfdom_sensor.so.4.0: cannot open shared object filecmeel-urdfdom 6.x 与新 ABI 不匹配安装cmeel-urdfdom4,5与cmeel-tinyxml211torch.cuda.is_available()返回FalseCUDA 轮子与驱动版本错位从 cu128 源重装 torch--index-url .../whl/cu128FFmpeg version: N/A或视频解码失败ffmpeg 未安装conda install ffmpeg -c conda-forgeModuleNotFoundError: No module named serial未装 hardware extrapip install -e .[hardware]相机列表为空pyrealsense2 缺失或版本越界pip install -e .[intelrealsense]lerobot-train: command not found未以可编辑模式安装或环境未激活pip install -e .后用which lerobot-train复查下一步精读 官方安装文档conda/uv 双路径、ffmpeg 安装策略与 CUDA 变体选择都在这一个文件里。动手跑 examples/ 下的示例脚本例如 ACT 训练示例 或 LeKiwi 回放流程把装好了变成用起来了。计划参与贡献的话先读 CONTRIBUTING.md再装开发依赖pip install -e .[dev]把 pre-commit 钩子挂上。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考