解决LeRobot安装9大痛点：从依赖冲突到硬件适配的完整指南

你是否在安装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超时或失败。

解决方案：

1. 更换conda源为国内镜像：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --set show_channel_urls yes

2. 若仍失败，使用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安装过程中的环境配置、依赖管理、硬件适配等关键环节的常见问题及解决方案。成功安装后，你可以：

1. 探索官方文档：docs/source/index.mdx
2. 尝试示例项目：examples/
3. 参与社区讨论：CONTRIBUTING.md

如果遇到本文未覆盖的问题，欢迎在项目GitHub Issues中提交详细错误报告，或加入Discord社区获取实时支持。

提示：定期更新项目代码可获得最新bug修复：git pull origin main && pip install -e .