LeRobot 安装避坑实战从环境准备到硬件验证的四段式完整清单【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobotLeRobot 安装最容易卡住的环节无非四类环境没配好、依赖起冲突、硬件没反应、装完不知道算不算成功。这篇文章按“环境、依赖、硬件、验证”四段梳理整个过程面向刚上手 SO100 级别机械臂或只想先在仿真里跑训练、评估的同学。读完后你会知道每一步该敲什么命令、失败时按哪个报错关键词快速定位。你卡在 LeRobot 安装的哪一段装机器人机器学习库的麻烦很少出在单条命令上更多出在阶段之间环境没就位就去装依赖、依赖没装全就去连硬件。先看下表确认自己属于哪一段再跳到对应章节阶段典型卡点对应章节环境Python 版本不对、conda 环境超时、WSL 缺设备库先确认系统与 Python 版本依赖解析器报冲突、编译失败、GPU 版本不匹配安装本体与按需选择 extras硬件电机没响应、相机找不到硬件连接电机与相机排查顺序验证不确定是否装好、不知道第一步跑什么验证安装如果报错信息里有明确关键词比如VersionConflict、command not found可以直接查文末的“常见报错关键词速查表”。先确认系统与 Python 版本LeRobot 当前要求 Python 3.12 及以上见 pyproject.toml 中requires-python声明。官方安装文档以 condaminiforge为主Ubuntu、WSL、macOS 均有覆盖详见 docs/source/installation.mdx。先检查当前版本python --version版本低于 3.12 时建议新建一个专用环境而不是直接改动系统 Pythonconda create -y -n lerobot python3.12 conda activate lerobot几点说明conda 解析慢或超时多半是网络问题换用镜像源仍不行可考虑uv路线uv python install 3.12后uv venv前提是配合较新的 PyTorch具体以安装文档为准。WSL 用户需要额外安装evdevconda 环境用conda install evdev -c conda-forge否则输入设备相关功能会报错。视频解码依赖 ffmpegLeRobot 默认用 TorchCodec 解视频需要 ffmpeg。conda 环境里执行conda install ffmpeg -c conda-forge最省事而 macOS Intel、Linux ARM 以及 Windows 上 PyTorch 低于 2.8 的平台会自动退回 pyav 解码这类机器不需要单独装 ffmpeg。安装本体与按需选择 extrasLeRobot 的基础安装刻意保持轻量只有核心 ML 依赖录数据、训练、连硬件等能力都放在 extras可选依赖组里按需组合即可。完整清单见 pyproject.toml 的[project.optional-dependencies]段。先克隆仓库并进入目录可执行安装模式方便随时看代码、改配置git clone https://gitcode.com/GitHub_Trending/le/lerobot cd lerobot pip install -e .[core_scripts]常用组合怎么选你要做什么安装的 extras说明录制、回放、标定core_scripts包含 dataset hardware viz训练策略training包含 dataset accelerate wandb评估evaluation另需对应策略与仿真环境的 extras全都要all含所有策略、环境、硬件与开发工具电机、相机、策略各有独立 extras装错或漏装是“硬件没反应”“策略加载失败”的最常见原因pip install -e .[feetech] # SO100/SO101/Moss 的 Feetech 电机 pip install -e .[dynamixel] # Koch v1.1 的 Dynamixel 电机 pip install -e .[intelrealsense] # RealSense 相机驱动 pip install -e .[pusht] # Pusht 仿真环境aloha 同理 pip install -e .[pi] # Pi0/Pi0.5/Pi0-FAST 策略依赖Linux 用户的 GPU 注意源码安装走uv时项目会把 torch/torchvision 固定到 CUDA 12.8 的 wheel 源驱动下限约 570.86。如果你的驱动更老或需要别的 CUDA 版本需显式指定--index-url重装 torch 后再装 lerobot具体取值以安装文档中的 “PyTorch CUDA variant” 一节为准。硬件连接电机与相机没响应时的排查顺序硬件连不上时按下面顺序检查基本能覆盖绝大多数情况确认串口设备存在插上机器人后执行ls -l /dev/ttyACM*或ttyUSB*看设备是否出现当前用户无读写权限时临时放开权限或把用户加入dialout组。跑官方寻址工具电机端用lerobot-find-port探测串口号与波特率相机端用lerobot-find-cameras列出可用相机。这两个命令的源码在 src/lerobot/scripts/参数可用--help查看。检查 extras 是否装对SO100/SO101/Moss 需要feetechKoch v1.1 需要dynamixelRealSense 需要intelrealsenseUbuntu 装 pyrealsense2、macOS 装 pyrealsense2-macosx版本下限由 pyproject 锁定。确认电机行程电机能通信后用lerobot-find-joint-limits自动检测各关节活动范围避免后面标定和遥操作时撞限位。各机型的具体接线与装配要求查 docs/source/hardware_guide.mdx 或对应机型文档如 docs/source/so100.mdx。常见报错关键词速查表报错关键词 / 现象最可能的原因第一步动作command not foundlerobot-* 命令环境没激活或该命令对应的 extras 没装conda activate lerobot后重试再装对应 extraVersionConflict、解析器长时间不收敛手动预装了版本不合的包与项目声明区间打架不要手工定版本按 pyproject.toml 的区间让解析器自己解如 torch 需落在 2.7 至 2.12 之间torch 与 torchvision 版本不匹配两者需成对升级对照 pyproject 中的版本区间成对重装av / pyrealsense2 编译失败缺系统级编译工具Ubuntusudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-devmacOSbrew install cmake pkg-config ffmpeg视频解码报错、找不到 ffmpeg平台支持 TorchCodec 但未装 ffmpegconda install ffmpeg -c conda-forge注意 macOS Intel、Linux ARM 等会自动退回 pyav无需处理WSL 下输入设备报错缺 evdevconda install evdev -c conda-forge电机无响应串口权限、extras 装错、波特率不对按上文四步排查先ls -l /dev/tty*再lerobot-find-portCUDA 相关错误Linux驱动与 torch 的 CUDA 版本不匹配确认驱动版本必要时按文档指定--index-url重装 torch验证安装从 lerobot-info 到跑通一次评估基础验证只需一条命令lerobot-info它能正常输出版本与系统信息说明核心库装好了。之后按你的目标加一层验证只做训练/评估装好training和一个策略 extra 后跑 examples/training/train_policy.py 对应的lerobot-train流程常用参数组合可查 docs/source/cheat-sheet.mdx。要连真机电机行程检测通过后按 examples/ 中对应机器人的示例如 teleoperate、record 脚本走一遍“遥操作—录数据—回放”。要跑仿真装pusht或aloha后用lerobot-eval做一次小规模评估确认策略、数据集、环境三方都通了。安装成功后的下一步系统看一遍从 docs/source/index.mdx 进入文档首页按“数据集 → 策略 → 硬件”的顺序了解各模块边界。跑个示例examples/tutorial/ 里有 ACT、Diffusion、Pi0 的端到端小例子适合第一次完整走流程。接自己的硬件读 docs/source/hardware_guide.mdx 和对应机型页如 docs/source/so100.mdx。参与或反馈按 CONTRIBUTING.md 的贡献指南提交 Issue 或 PR日常问题可到项目 Discord 社区提问。版本迭代较快遇到本文未覆盖的情况优先以仓库内 docs/source/installation.mdx 和 pyproject.toml 的最新内容为准。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LeRobot 安装避坑实战：从环境准备到硬件验证的四段式完整清单
LeRobot 安装避坑实战从环境准备到硬件验证的四段式完整清单【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobotLeRobot 安装最容易卡住的环节无非四类环境没配好、依赖起冲突、硬件没反应、装完不知道算不算成功。这篇文章按“环境、依赖、硬件、验证”四段梳理整个过程面向刚上手 SO100 级别机械臂或只想先在仿真里跑训练、评估的同学。读完后你会知道每一步该敲什么命令、失败时按哪个报错关键词快速定位。你卡在 LeRobot 安装的哪一段装机器人机器学习库的麻烦很少出在单条命令上更多出在阶段之间环境没就位就去装依赖、依赖没装全就去连硬件。先看下表确认自己属于哪一段再跳到对应章节阶段典型卡点对应章节环境Python 版本不对、conda 环境超时、WSL 缺设备库先确认系统与 Python 版本依赖解析器报冲突、编译失败、GPU 版本不匹配安装本体与按需选择 extras硬件电机没响应、相机找不到硬件连接电机与相机排查顺序验证不确定是否装好、不知道第一步跑什么验证安装如果报错信息里有明确关键词比如VersionConflict、command not found可以直接查文末的“常见报错关键词速查表”。先确认系统与 Python 版本LeRobot 当前要求 Python 3.12 及以上见 pyproject.toml 中requires-python声明。官方安装文档以 condaminiforge为主Ubuntu、WSL、macOS 均有覆盖详见 docs/source/installation.mdx。先检查当前版本python --version版本低于 3.12 时建议新建一个专用环境而不是直接改动系统 Pythonconda create -y -n lerobot python3.12 conda activate lerobot几点说明conda 解析慢或超时多半是网络问题换用镜像源仍不行可考虑uv路线uv python install 3.12后uv venv前提是配合较新的 PyTorch具体以安装文档为准。WSL 用户需要额外安装evdevconda 环境用conda install evdev -c conda-forge否则输入设备相关功能会报错。视频解码依赖 ffmpegLeRobot 默认用 TorchCodec 解视频需要 ffmpeg。conda 环境里执行conda install ffmpeg -c conda-forge最省事而 macOS Intel、Linux ARM 以及 Windows 上 PyTorch 低于 2.8 的平台会自动退回 pyav 解码这类机器不需要单独装 ffmpeg。安装本体与按需选择 extrasLeRobot 的基础安装刻意保持轻量只有核心 ML 依赖录数据、训练、连硬件等能力都放在 extras可选依赖组里按需组合即可。完整清单见 pyproject.toml 的[project.optional-dependencies]段。先克隆仓库并进入目录可执行安装模式方便随时看代码、改配置git clone https://gitcode.com/GitHub_Trending/le/lerobot cd lerobot pip install -e .[core_scripts]常用组合怎么选你要做什么安装的 extras说明录制、回放、标定core_scripts包含 dataset hardware viz训练策略training包含 dataset accelerate wandb评估evaluation另需对应策略与仿真环境的 extras全都要all含所有策略、环境、硬件与开发工具电机、相机、策略各有独立 extras装错或漏装是“硬件没反应”“策略加载失败”的最常见原因pip install -e .[feetech] # SO100/SO101/Moss 的 Feetech 电机 pip install -e .[dynamixel] # Koch v1.1 的 Dynamixel 电机 pip install -e .[intelrealsense] # RealSense 相机驱动 pip install -e .[pusht] # Pusht 仿真环境aloha 同理 pip install -e .[pi] # Pi0/Pi0.5/Pi0-FAST 策略依赖Linux 用户的 GPU 注意源码安装走uv时项目会把 torch/torchvision 固定到 CUDA 12.8 的 wheel 源驱动下限约 570.86。如果你的驱动更老或需要别的 CUDA 版本需显式指定--index-url重装 torch 后再装 lerobot具体取值以安装文档中的 “PyTorch CUDA variant” 一节为准。硬件连接电机与相机没响应时的排查顺序硬件连不上时按下面顺序检查基本能覆盖绝大多数情况确认串口设备存在插上机器人后执行ls -l /dev/ttyACM*或ttyUSB*看设备是否出现当前用户无读写权限时临时放开权限或把用户加入dialout组。跑官方寻址工具电机端用lerobot-find-port探测串口号与波特率相机端用lerobot-find-cameras列出可用相机。这两个命令的源码在 src/lerobot/scripts/参数可用--help查看。检查 extras 是否装对SO100/SO101/Moss 需要feetechKoch v1.1 需要dynamixelRealSense 需要intelrealsenseUbuntu 装 pyrealsense2、macOS 装 pyrealsense2-macosx版本下限由 pyproject 锁定。确认电机行程电机能通信后用lerobot-find-joint-limits自动检测各关节活动范围避免后面标定和遥操作时撞限位。各机型的具体接线与装配要求查 docs/source/hardware_guide.mdx 或对应机型文档如 docs/source/so100.mdx。常见报错关键词速查表报错关键词 / 现象最可能的原因第一步动作command not foundlerobot-* 命令环境没激活或该命令对应的 extras 没装conda activate lerobot后重试再装对应 extraVersionConflict、解析器长时间不收敛手动预装了版本不合的包与项目声明区间打架不要手工定版本按 pyproject.toml 的区间让解析器自己解如 torch 需落在 2.7 至 2.12 之间torch 与 torchvision 版本不匹配两者需成对升级对照 pyproject 中的版本区间成对重装av / pyrealsense2 编译失败缺系统级编译工具Ubuntusudo apt-get install cmake build-essential python3-dev pkg-config libavformat-dev libavcodec-devmacOSbrew install cmake pkg-config ffmpeg视频解码报错、找不到 ffmpeg平台支持 TorchCodec 但未装 ffmpegconda install ffmpeg -c conda-forge注意 macOS Intel、Linux ARM 等会自动退回 pyav无需处理WSL 下输入设备报错缺 evdevconda install evdev -c conda-forge电机无响应串口权限、extras 装错、波特率不对按上文四步排查先ls -l /dev/tty*再lerobot-find-portCUDA 相关错误Linux驱动与 torch 的 CUDA 版本不匹配确认驱动版本必要时按文档指定--index-url重装 torch验证安装从 lerobot-info 到跑通一次评估基础验证只需一条命令lerobot-info它能正常输出版本与系统信息说明核心库装好了。之后按你的目标加一层验证只做训练/评估装好training和一个策略 extra 后跑 examples/training/train_policy.py 对应的lerobot-train流程常用参数组合可查 docs/source/cheat-sheet.mdx。要连真机电机行程检测通过后按 examples/ 中对应机器人的示例如 teleoperate、record 脚本走一遍“遥操作—录数据—回放”。要跑仿真装pusht或aloha后用lerobot-eval做一次小规模评估确认策略、数据集、环境三方都通了。安装成功后的下一步系统看一遍从 docs/source/index.mdx 进入文档首页按“数据集 → 策略 → 硬件”的顺序了解各模块边界。跑个示例examples/tutorial/ 里有 ACT、Diffusion、Pi0 的端到端小例子适合第一次完整走流程。接自己的硬件读 docs/source/hardware_guide.mdx 和对应机型页如 docs/source/so100.mdx。参与或反馈按 CONTRIBUTING.md 的贡献指南提交 Issue 或 PR日常问题可到项目 Discord 社区提问。版本迭代较快遇到本文未覆盖的情况优先以仓库内 docs/source/installation.mdx 和 pyproject.toml 的最新内容为准。【免费下载链接】lerobot LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考