LeRobot完整安装指南：从零到一部署机器人AI框架的实战手册

LeRobot完整安装指南：从零到一部署机器人AI框架的实战手册

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot

LeRobot是一个专注于真实世界机器人应用的PyTorch框架，提供了模型、数据集和工具的统一接口。本文将通过问题导向的方式，帮助你从零开始成功部署这个先进的机器人AI框架，涵盖环境配置、依赖管理、硬件适配等关键环节，让你快速掌握LeRobot的核心功能和应用场景。

📋 核心关键词与项目定位

核心关键词：LeRobot安装、机器人AI框架、PyTorch机器人、硬件适配、依赖管理
长尾关键词：LeRobot环境配置、机器人控制框架、多模态机器人学习

LeRobot旨在通过标准化的Python接口和统一的数据格式，降低机器人AI的开发门槛。无论你是研究学者还是机器人开发者，都能通过本文掌握完整的部署流程。

🚀 环境准备与系统兼容性检查

在开始安装之前，需要确保系统环境满足基本要求。LeRobot主要支持Ubuntu和macOS系统，建议使用Python 3.12或更高版本。

系统依赖检查

首先检查Python版本和系统环境：

python --version # 应显示Python 3.12.x或更高版本 uname -a # 确认操作系统类型和架构

虚拟环境创建策略

创建隔离的Python环境是避免依赖冲突的关键。LeRobot支持多种环境管理工具：

# 方法1：使用conda（推荐） conda create -y -n lerobot python=3.12 conda activate lerobot # 方法2：使用uv（适用于PyTorch ≥ 2.10） uv python install 3.12 uv venv --python 3.12 source .venv/bin/activate

专业提示：如果在WSL（Windows子系统Linux）中安装，需要额外安装evdev包：

# conda环境 conda install evdev -c conda-forge # uv环境 sudo apt install libevdev-dev uv pip install evdev

📦 核心依赖安装与版本管理

LeRobot的核心依赖管理通过pyproject.toml文件实现，但实际安装过程中常遇到版本冲突问题。

基础框架安装

最简单的安装方式是使用pip直接安装：

pip install lerobot

安装完成后验证基础功能：

lerobot-info

如果看到LeRobot的版本信息和系统配置输出，说明基础安装成功。

可选功能模块安装

LeRobot采用模块化设计，可以根据需求安装特定功能：

# 安装所有功能（包含仿真环境和硬件支持） pip install 'lerobot[all]' # 仅安装Feetech电机支持 pip install 'lerobot[feetech]' # 安装特定机器人策略支持 pip install 'lerobot[smolvla]' pip install 'lerobot[groot]'

视频解码依赖配置

LeRobot使用TorchCodec进行视频解码，这需要正确的ffmpeg配置：

# 对于conda用户 conda install ffmpeg -c conda-forge # 如果遇到版本兼容问题，可指定版本 conda install ffmpeg=7.1.1 -c conda-forge

注意：TorchCodec在macOS Intel（x86_64）、Linux ARM架构或Windows上的PyTorch < 2.8环境中不可用。在这些平台上，LeRobot会自动回退到pyav，无需安装ffmpeg。

🔧 硬件设备适配与驱动安装

LeRobot支持多种机器人硬件平台，包括SO系列机械臂、Reachy 2人形机器人等。硬件适配是安装过程中的关键环节。

电机驱动配置

根据机器人型号选择对应的电机驱动：

# Feetech电机（SO100/SO101/Moss机器人） pip install -e ".[feetech]" # Dynamixel电机（Koch v1.1机器人） pip install -e ".[dynamixel]"

安装完成后，可以使用内置工具检测硬件连接：

# 查找可用串口 python src/lerobot/scripts/lerobot_find_port.py # 检测相机设备 python src/lerobot/scripts/lerobot_find_cameras.py

相机设备支持

对于需要视觉输入的机器人应用，LeRobot提供了多种相机支持：

# Realsense相机驱动（Ubuntu） pip install pyrealsense2>=2.55.1.6486 # Realsense相机驱动（macOS） pip install pyrealsense2-macosx>=2.54

图：LeRobot的多模态视觉-语言-动作架构，展示了从视觉输入到机器人控制的完整流程

🛠️ 常见安装问题与解决方案

问题1：PyTorch版本冲突

症状：安装过程中出现"VersionConflict"错误，特别是torch与torchvision版本不匹配。

解决方案：手动指定兼容版本：

pip install "torch>=2.2.1,<2.8.0" "torchvision>=0.21.0,<0.23.0"

问题2：编译依赖缺失

症状：安装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

问题3：硬件通信权限问题

症状：电机或相机设备无法访问，提示权限不足。

解决方案：配置设备权限：

# 串口设备权限 sudo chmod 666 /dev/ttyUSB0 sudo usermod -a -G dialout $USER # 相机设备权限 sudo usermod -a -G video $USER

问题4：环境激活异常

症状：激活环境后，运行LeRobot命令仍提示"command not found"。

验证方法：检查环境变量：

echo $CONDA_PREFIX # 应显示包含"lerobot"的路径 which python # 应显示虚拟环境中的Python路径

🧪 安装验证与功能测试

基础功能验证

安装完成后，运行以下命令验证核心功能：

# 检查LeRobot基本信息 lerobot-info # 测试数据集功能 python -c "from lerobot import __version__; print(f'LeRobot version: {__version__}')" # 验证关键模块导入 python -c "import lerobot; print('Import successful')"

仿真环境测试

通过仿真环境验证完整功能链：

# 安装仿真环境依赖 pip install -e ".[pusht]" # 运行示例回放 python examples/lekiwi/replay.py

如果看到机器人在仿真环境中执行任务，说明安装成功。

硬件连接测试

对于有实际硬件的用户，可以进行设备连接测试：

# 检测关节限位（SO100机器人示例） lerobot-find-joint-limits --robot so100_follower # 测试相机流 python examples/dataset/use_dataset_tools.py --camera_test

图：SO100双机械臂机器人执行协作任务，展示了LeRobot在实际硬件上的应用

📊 不同系统的依赖对比

为了帮助你更好地理解不同平台的需求，这里整理了Ubuntu和macOS的主要依赖差异：

🎯 最佳实践与优化建议

1. 使用conda环境管理

虽然LeRobot支持多种环境工具，但conda在管理复杂依赖时表现最佳：

# 创建专用环境 conda create -y -n lerobot python=3.12 conda activate lerobot # 安装系统依赖 conda install ffmpeg -c conda-forge conda install pytorch torchvision -c pytorch

2. 分步安装策略

建议采用分步安装策略，逐步验证每个模块：

# 步骤1：基础框架 pip install lerobot # 步骤2：验证基础功能 lerobot-info # 步骤3：安装特定功能 pip install 'lerobot[feetech]' # 步骤4：测试硬件连接 python src/lerobot/scripts/lerobot_find_port.py

3. 定期更新维护

保持LeRobot和相关依赖的最新状态：

# 更新项目代码 git clone https://gitcode.com/GitHub_Trending/le/lerobot cd lerobot # 更新依赖 pip install --upgrade -e .

🔍 故障排除工具箱

当遇到安装问题时，可以使用以下诊断工具：

# 检查Python环境 python -c "import sys; print(f'Python {sys.version}')" # 检查PyTorch安装 python -c "import torch; print(f'PyTorch {torch.__version__}, CUDA: {torch.cuda.is_available()}')" # 检查LeRobot模块 python -c "import lerobot; print(dir(lerobot))" # 查看已安装包 pip list | grep -E "(torch|lerobot|transformers)"

图：LeRobot在实际机器人控制场景中的应用，展示了框架的实时控制能力

📚 深入学习资源

成功安装LeRobot后，可以进一步探索以下资源：

1. 官方文档：docs/source/installation.mdx - 详细的安装和配置指南
2. 示例项目：examples/ - 包含多种应用场景的代码示例
3. 策略算法：src/lerobot/policies/ - 各种机器人控制策略的实现
4. 硬件接口：src/lerobot/robots/ - 不同机器人平台的接口代码
5. 数据集工具：src/lerobot/datasets/ - 数据处理和管理的工具集

💡 实用小贴士

• 网络问题：如果pip安装速度慢，可以使用国内镜像源：

  pip install -i https://pypi.tuna.tsinghua.edu.cn/simple lerobot

• 内存优化：大型模型训练时，可以调整PyTorch内存分配策略：

  export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128

• 开发模式：如果需要修改源码，使用开发模式安装：

  pip install -e .

• 版本锁定：对于生产环境，建议锁定依赖版本：

  pip freeze > requirements.txt

🎉 总结与下一步

通过本文的指导，你应该已经成功完成了LeRobot的安装和基础配置。这个强大的机器人AI框架为你提供了：

• 🚀 标准化的机器人控制接口
• 📊 统一的数据集格式和管理工具
• 🧠 先进的多模态学习算法
• 🔧 丰富的硬件适配支持

接下来，你可以：

1. 运行示例项目，熟悉框架的基本用法
2. 连接实际硬件，测试机器人控制功能
3. 探索预训练模型，了解现有算法的性能
4. 参与社区讨论，获取更多技术支持

如果在使用过程中遇到问题，可以参考项目中的CONTRIBUTING.md文档，或在社区中寻求帮助。记住，成功的机器人AI应用不仅需要正确的安装，更需要持续的学习和实践。

最后提醒：机器人开发涉及硬件操作，请始终注意安全规范，特别是在测试实际机器人时确保有适当的保护措施。

【免费下载链接】lerobot🤗 LeRobot: Making AI for Robotics more accessible with end-to-end learning项目地址: https://gitcode.com/GitHub_Trending/le/lerobot