解决LeRobot安装9大痛点：从依赖冲突到硬件适配的完整指南
项目地址: https://gitcode.com/GitHub_Trending/le/lerobot 你是否在安装LeRobot时遇到过conda环境配置失败、依赖包版本冲突、硬件驱动不识别等问题？本文将系统梳理安装过程中的9类常见问题，提供分步解决方案和最佳实践，确保你顺利部署这个用于现实世界机器人的最先进机器学习框架。读完本文后，你将能够：快速定位安装错误类型、解决跨平台依赖问题、配置硬件设备通信，并通过测试用例验证安装完整性。
系统环境准备
LeRobot支持Ubuntu和macOS系统，在开始安装前需确认操作系统版本和Python环境。官方推荐使用Python 3.10，可通过以下命令检查当前Python版本：
python --version
若版本不符，需安装指定版本Python。Ubuntu用户可使用deadsnakes PPA，macOS用户推荐使用Homebrew。项目提供了系统专用依赖文件：
- Ubuntu系统依赖：requirements-ubuntu.txt
- macOS系统依赖：requirements-macos.txt
虚拟环境配置
Conda环境创建失败
问题表现：执行conda create -y -n lerobot python=3.10时出现Solving environment超时或失败。
解决方案：
- 更换conda源为国内镜像：
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --set show_channel_urls yes
- 若仍失败，使用mamba加速环境创建：
conda install -c conda-forge mamba
mamba create -y -n lerobot python=3.10
环境激活问题
问题表现：激活环境后，运行LeRobot命令仍提示"command not found"。
验证方法：检查环境是否正确激活：
echo $CONDA_PREFIX
应显示包含"lerobot"的路径。如未激活，需重新执行：
conda activate lerobot
依赖包安装
基础依赖安装
核心依赖安装命令：
pip install -e .
该命令会根据pyproject.toml中的配置安装基础组件。对于需要额外功能（如特定机器人支持、策略算法等），可安装可选依赖：
pip install 'lerobot[all]' # 所有功能
pip install 'lerobot[feetech]' # Feetech电机支持
pip install 'lerobot[smolvla]' # SmolVLA策略支持
版本冲突解决
问题表现：安装过程中出现"VersionConflict"错误，特别是torch与torchvision版本不匹配。
解决方案：参考pyproject.toml中指定的版本范围，安装兼容版本：
pip install "torch>=2.2.1,<2.8.0" "torchvision>=0.21.0,<0.23.0"
编译错误处理
问题表现：安装av或pyrealsense2时出现编译错误，提示缺少cmake或编译器。
解决方案：安装系统编译工具：
# Ubuntu
sudo apt-get install cmake build-essential python-dev pkg-config libavformat-dev libavcodec-dev
# macOS
brew install cmake pkg-config ffmpeg
详细编译指南可参考官方文档。
硬件设备配置
电机驱动安装
LeRobot支持Dynamixel和Feetech两种电机系统，需根据机器人型号安装对应驱动：
Feetech电机（SO100/SO101/Moss）：
pip install -e ".[feetech]"
Dynamixel电机（Koch v1.1）：
pip install -e ".[dynamixel]"
电机通信测试工具：src/lerobot/scripts/lerobot_find_port.py
相机设备连接
Realsense相机用户需安装专用驱动：
# Ubuntu
pip install pyrealsense2>=2.55.1.6486
# macOS
pip install pyrealsense2-macosx>=2.54
相机检测工具：src/lerobot/scripts/lerobot_find_cameras.py
安装验证
基础功能测试
安装完成后，运行信息查询命令验证基础功能：
lerobot-info
若输出LeRobot版本信息和系统配置，则基础安装成功。
仿真环境测试
通过运行Pusht仿真环境验证完整功能：
pip install -e ".[pusht]"
python examples/lekiwi/replay.py
成功运行将显示机器人在仿真环境中执行任务的过程。
硬件通信测试
对于连接硬件的用户，可运行关节限位检测工具：
lerobot-find-joint-limits --robot so100_follower
该工具会自动检测电机运动范围并生成配置文件。
常见问题速查表
| 错误类型 | 可能原因 | 解决方案 |
|---|---|---|
| Conda环境创建失败 | 网络问题或conda版本过旧 | 更换国内源或更新conda |
| torch安装失败 | CUDA版本不匹配 | 安装CPU版本或匹配CUDA版本 |
| 电机无响应 | 串口权限不足 | sudo chmod 666 /dev/ttyUSB0 |
| 相机无法打开 | 驱动版本不兼容 | 安装项目指定版本驱动 |
| 策略加载失败 | 缺少模型权重 | 运行lerobot-download-weights |
总结与后续步骤
本文详细介绍了LeRobot安装过程中的环境配置、依赖管理、硬件适配等关键环节的常见问题及解决方案。成功安装后，你可以：
- 探索官方文档：docs/source/index.mdx
- 尝试示例项目：examples/
- 参与社区讨论：CONTRIBUTING.md
如果遇到本文未覆盖的问题，欢迎在项目GitHub Issues中提交详细错误报告，或加入Discord社区获取实时支持。
提示：定期更新项目代码可获得最新bug修复：
git pull origin main && pip install -e .
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
