5分钟搞定Genesis依赖安装：Ubuntu系统避坑指南

为什么选择Genesis？

Genesis是一个为通用机器人和具身AI学习设计的生成式物理引擎平台，支持刚性体、液体、气体、可变形物体等多种物理模拟，在Ubuntu系统下的高效部署是开展相关研究的基础。项目核心特性包括超430000倍实时速度的物理模拟、跨平台兼容性和照片级渲染能力，详细介绍可参考项目README。

系统环境准备

在开始安装前，请确保您的Ubuntu系统满足以下要求：

• 操作系统：Ubuntu 20.04 LTS或22.04 LTS
• Python版本：3.10-3.13（推荐3.10）
• 显卡要求：Nvidia GPU（推荐RTX 4090以获得最佳性能）或AMD GPU（需使用Vulkan后端）

基础系统依赖安装

首先安装系统级依赖，打开终端执行以下命令：

sudo apt update && sudo apt install -y \
    build-essential \
    libgl1-mesa-glx \
    libglib2.0-0 \
    libx11-dev \
    libxext-dev \
    libxcursor-dev \
    libxrandr-dev \
    libxinerama-dev \
    libxi-dev \
    libxxf86vm-dev \
    libglfw3-dev \
    libgles2-mesa-dev \
    libopenexr-dev \
    libfreetype6-dev \
    git

这些依赖涵盖了图形渲染、字体处理和基础编译工具，是运行Genesis的基础。

Python环境配置

创建虚拟环境

推荐使用venv创建隔离的Python环境：

python3.10 -m venv genesis-env
source genesis-env/bin/activate

升级pip

确保pip版本最新以避免安装错误：

pip install --upgrade pip

PyTorch安装

Genesis依赖特定版本的PyTorch，根据您的CUDA版本选择合适的安装命令：

CUDA 12.1用户：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

CPU用户：

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

更多安装选项可参考PyTorch官方文档。

Genesis核心依赖安装

通过PyPI安装（推荐）

对于普通用户，直接通过PyPI安装最新稳定版：

pip install genesis-world

开发版安装

如需贡献代码或体验最新特性，使用源码安装：

git clone https://gitcode.com/GitHub_Trending/genesi/Genesis.git
cd Genesis
pip install -e ".[dev]"

关键依赖说明

根据pyproject.toml定义，Genesis主要依赖包括：

• gstaichi==2.4.0：高性能计算后端
• numpy>=1.26.4：数值计算基础
• mujoco>=3.2.5：机器人仿真支持
• trimesh：网格处理库
• libigl：几何处理算法库

安装过程中会自动处理这些依赖，但建议监控安装日志以确保没有遗漏。

Docker安装方案（可选）

对于希望快速部署的用户，项目提供了Docker支持：

Nvidia GPU用户

docker build -t genesis -f docker/Dockerfile docker
xhost +local:root
docker run --gpus all --rm -it \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix/:/tmp/.X11-unix \
    -v $(pwd):/workspace \
    --name genesis genesis:latest

AMD GPU用户

使用专门的AMD Dockerfile：

docker build -t genesis-amd -f docker/Dockerfile.amdgpu docker
xhost +local:docker
docker run -it --network=host \
    --device=/dev/kfd \
    --device=/dev/dri \
    --group-add=video \
    -v $PWD:/workspace \
    -e DISPLAY=$DISPLAY \
    genesis-amd

Docker配置文件位于docker/目录，包含Nvidia和AMD显卡的支持配置。

验证安装

安装完成后，运行示例程序验证环境：

python examples/hello_genesis.py

成功运行将显示Genesis的logo和版本信息。您也可以尝试更复杂的示例，如机械臂仿真：

python examples/rigid/single_franka.py

常见问题解决

依赖冲突

如果遇到版本冲突，可创建新的虚拟环境并严格按照要求安装依赖版本。

图形渲染问题

• Nvidia用户确保安装了正确的CUDA驱动
• AMD用户需在初始化时指定Vulkan后端：gs.init(vulkan)

编译错误

若源码安装时出现编译错误，检查是否安装了所有系统依赖：

sudo apt install -y cython3 libigl-dev

总结

本指南涵盖了Genesis在Ubuntu系统下的完整依赖安装流程，从系统准备到环境验证，帮助您快速搭建开发环境。项目依赖定义在pyproject.toml中，更多高级配置和优化可参考官方文档。

建议收藏本文以备后续环境迁移使用，如有安装问题可通过项目GitHub Issues获取支持。

Genesis物理引擎支持多种复杂场景模拟