这两天我一直在跟一台 Ubuntu 20.04 的机器较劲——准确说是在给这台老系统装 Genesis最新。这个框架最近在机器人仿真和数据生成领域热度很高它用 Python 作为入口底层却是一整套 C 物理引擎和渲染器。这句话意味着什么意味着你没法像装一个纯 Python 库那样轻松系统里任何一个基础组件不够新都会在最后的 import 阶段爆发问题。我这次安装踩了不少坑尤其这几点20.04 默认的 gcc 是 9.3、glibc 是 2.31而最新版 Genesis 对 Python 版本、CUDA、PyTorch 组合都有要求。网上能找到的大多数教程是在 22.04 或者更新的环境上写的拿到 20.04 上往往差一步就装不上。这篇不打算复述文档而是记录我实测通过的完整链路以及一些“文档不会写但你必须知道”的注意事项。如果你准备在 Ubuntu 20.04 上装 Genesis无论是为了做机器人仿真、批量渲染还是生成训练数据集按这条链路走能省掉一大半排查时间。1. 安装前的思路梳理Genesis 是什么到底难在哪1.1 Genesis 能做什么我为什么选它先把概念对齐。Genesis 不是某个单一的“安装包”而是一套偏向机器人领域的仿真工具链。它给开发者提供 Python 接口让你能快速搭建包含刚体、铰链、关节、传感器、相机在内的虚拟场景然后跑物理仿真或者批量生成训练数据。对我个人来说最吸引人的是两件事一是场景搭建的代码非常简洁几行就能摆出一个有物理效果的测试环境二是它对大规模并行仿真做了专门的优化适合用来做强化学习前的策略验证和数据采集。不过也要提醒一句市面上叫 Genesis 的项目不止一个。如果你在别的地方看到同名工具先确认它是否依赖 PyTorch、是否有原生 C 扩展。下面的安装思路适用于这一类带编译依赖的项目如果是纯 Python 的小工具安装难度会低很多直接照后面的 pip 思路来也没有问题。为什么 Ubuntu 20.04 尤其麻烦因为这个系统正好处在一个比较尴尬的“新旧交界点”。它自带的 glibc 版本普遍是 2.31默认 gcc 是 9.3很多新版本的开源项目在编译时都会优先考虑 22.04 或更新的系统。你拿着一个最新版 Genesis 的代码想在 20.04 上从源码编译第一关就会碰到工具链版本不匹配。更麻烦的是这类问题往往不会在pip install阶段立刻报错而是等你运行import genesis时才把缺库、符号找不到、段错误这些问题一并炸出来。1.2 先确定运行模式GPU 还是 CPU安装之前我建议你先把“要不要用 GPU”这件事想清楚因为它直接决定了后面的 PyTorch 安装方式。如果你手头有独立显卡而且驱动能正常识别那么安装完 Genesis 之后可以用 GPU 后端跑仿真速度会快非常多。尤其是批量并行场景GPU 模式下的效率优势几乎是碾压级的。但 GPU 模式对驱动版本、CUDA 版本、PyTorch 版本三者的一致性有要求任何一个错位都可能导致torch.cuda.is_available()返回 False。如果暂时没有独立显卡或者只是想在开发机上先把功能跑通CPU 模式也能用。只是遇到稍微复杂的场景会明显变慢。我的建议是第一次安装先不要追求 GPU 一步到位先保证import genesis能成功再回头处理 GPU 加速。这个顺序能帮你少踩一半的坑。1.3 动手前先做四个检查项这里我列了一个检查清单。每次换机器重装我都会先做这一步十几分钟就能避免后面一整天的折腾。检查项推荐状态说明系统版本Ubuntu 20.04.x20.04 可以装但要注意默认工具链偏旧Python 版本3.10 或 3.1120.04 默认的 3.8 太老强烈建议用 conda 另建环境编译工具链gcc/g 9 以上推荐新一点如果源码编译失败优先升级工具链显卡驱动能跑nvidia-smi看 Driver Version 和 CUDA 兼容版本决定 torch 怎么装顺便解释一个非常容易混淆的点nvidia-smi里显示的 CUDA 版本不代表你系统里已经安装好了 CUDA Toolkit。它更像是“当前驱动最多能支持到什么 CUDA 版本”。而 PyTorch 官方提供的 wheel 包内部已经包含了自己需要的 CUDA 运行时所以通常你不需要单独装完整版 CUDA Toolkit。只有在从源码编译一些带 CUDA 扩展的库时才可能需要nvcc。后面我会给出更具体的判断方法。2. 环境准备把 Ubuntu 20.04 调成可安装状态2.1 先更新系统补齐基础编译工具不管你要装什么我强烈建议先跑一遍系统更新。20.04 的软件源里的包版本普遍偏旧不更新的话后面很多依赖会装上一些“看起来能用但版本不对”的库。sudo apt update sudo apt upgrade -y更新完之后把编译和网络相关的基础工具一次性装好sudo apt install -y build-essential git wget curl cmake ninja-build \ libgl1 libglib2.0-0 libegl1 libxrender1 libxext6这里面有几个库专门说一下吧。libgl1是 OpenGL 渲染需要的运行时库很多图形相关的库 import 时都会去找libGL.so.120.04 上如果你装的是精简版桌面环境非常容易缺它。libglib2.0-0是 GLib 的运行时库常见的底层原生库都要用到。ninja-build能显著加快 CMake 项目的编译速度装了你不会后悔。注意如果你的系统已经用了一段时间更新完内核后建议重启一次避免后面编译时用到新工具链却因为内核和驱动没对齐而出现奇怪的问题。2.2 用 conda 单独建一个 Python 环境Ubuntu 20.04 自带的是 Python 3.8这个版本对最新版 Genesis 来说基本不在推荐范围。我这次用的是 conda 环境理由很简单conda 能让你在环境内部安装较新的 Python也能方便地切换编译器版本解决 20.04 自带工具链过旧的问题。如果你还没装 conda建议先装一个 Miniconda体积小够用。然后执行conda create -n genesis python3.10 -y conda activate genesis为什么推荐 3.10 而不是 3.12因为很多带编译扩展的科学计算库对新版本 Python 的发布节奏总是慢半拍。Genesis 作为一个对依赖链要求很高的项目3.10 或 3.11 是当前兼容性最稳的区域。我在这台机器上用的是 3.10跑通之后所有功能都正常。不直接往系统 Python 里装还有一个重要原因系统自带的 Python 被很多系统工具依赖如果为了装项目强灌一堆新版本库容易把系统搞坏。用 conda 环境隔离等于给这套工具链建了一个独立房间住坏了也不影响主系统。2.3 显卡驱动检查和 torch 版本匹配这一步是 GPU 能不能用的关键。我先执行nvidia-smi看输出里的 Driver Version 和右上角 CUDA Version。比如看到CUDA Version: 12.1意思是这张卡当前驱动可以支持到 CUDA 12.1。这并不代表已经装了 CUDA Toolkit只是给你一个选择 torch 的参考上限。接下来大致按这个原则选驱动支持的 CUDA 上限推荐的 torch 版本说明11.xcu118老驱动20.04 早期机器很常见12.0 及以上cu121 或 cu124新驱动优先选 cu121 更稳没有 nvidia-smiCPU 模式先保证能装后续再处理显卡如果你发现nvidia-smi提示找不到命令也有可能是驱动确实没装好。20.04 在部分显卡上需要手动安装驱动这里不展开讲因为不同显卡差异太大。建议先通过驱动命令列表查看可用的驱动装完后再重新执行nvidia-smi。如果你只是想验证 Genesis 能否工作CPU 模式也能继续走下去。3. 核心实现源码安装与快速验证3.1 两条安装路线怎么选目前 Genesis 的安装主要分两条路直接装发布版包或者 clone 源码后本地安装。直接装发布版包的好处是省心适合大多数只想使用、不打算改框架源码的人。命令是pip install genesis-world注意包名不是genesis。很多老教程里直接写pip install genesis装出来可能是另一个无关项目会让你在 import 时一脸迷茫。我这次先用pip index versions genesis-world确认了能拉到的版本再往下走。另一条路是源码安装。如果你需要修改引擎内部逻辑、Debug 原生层或者项目中要基于未发布的新特性开发那就得 clone 代码仓库git clone 项目仓库地址 cd genesis pip install -e .-e是 editable 模式意思是源码文件夹改动后不需要重新安装改完立刻生效。但这条路的编译依赖更重20.04 上的失败率也更高。我的建议是第一次尝试优先走发布版安装先把链路跑通再按需转源码模式。3.2 先装 PyTorch再装 Genesis如果你的机器要用 GPU 后端这一步的顺序非常重要。PyTorch 如果从默认 PyPI 源装很多情况下会装成 CPU 版本这样后面 Genesis 即使装了也没有办法调用 GPU 加速。先在 genesis 环境里安装与驱动匹配的 PyTorch。以 CUDA 12.1 为例conda activate genesis pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121如果你的驱动只支持 CUDA 11.8就把 URL 改成https://download.pytorch.org/whl/cu118。这里要注意如果你先安装了 CPU 版 torch后面想再切 GPU 版本最好是先卸载干净pip uninstall -y torch torchvision否则会出现各种“看似装了实际仍是旧版本”的问题。装完以后可以用一行命令验证python -c import torch; print(torch.__version__, torch.cuda.is_available())如果输出末尾是True说明 GPU 版本已经可用了。如果是False先不要急着装 Genesis把 torch 这一步解决干净不然后面所有报错都很难定位。torch 就绪后再装 Genesispip install genesis-world这里我不建议在没装 torch 的情况下直接执行这一步虽然 Genesis 的依赖声明里可能也会带 torch但那样很可能给你拉到 CPU 版本。你手动把 torch 装好等于把最不可控的因素提前控制住了。3.3 一次通过的验证流程安装成功后先做最基础的 import 测试不要一上来就跑你的业务代码python -c import genesis; print(genesis import ok)如果这一步能过说明 Python 层依赖已经基本齐全。如果报错绝大多数会集中在缺动态库。你可以先按后面“常见问题”那一节对照处理。接着做一个轻量级初始化。Genesis 的初始化方法在不同版本里略有区别有的写gs.init(backendgs.gpu)有的写gs.init(backendgs.cuda)。我做兼容性验证时会这样写import genesis as gs backend gs.gpu if hasattr(gs, gpu) else gs.cuda gs.init(backendbackend) print(backend:, backend)这段代码的好处是不管当前版本暴露出来的属性是哪个都能选中一个可用的后端。如果机器没有 GPU可以把backend改成gs.cpu再测。初始化成功之后再往下跑正式的物理仿真 Demo就只是时间问题了。4. 常见问题与排查技巧实录这一节我按真实踩坑频率排了个序。你在安装过程中遇到的 90% 的问题基本都能在这里找到对应解法。4.1 import 时报错 libGL.so.1 找不到这个报错我见得最多形式一般是ImportError: libGL.so.1: cannot open shared object file: No such file or directory原因是系统缺少 OpenGL 运行时库。解决方式很简单sudo apt install -y libgl1如果还报了libglib-2.0.so.0相关再补一个sudo apt install -y libglib2.0-0装完以后重新跑 import 测试基本就过了。这类问题属于“环境相关”不是 Genesis 本身的 bug所以你在其他项目里遇到类似缺失也可以按这个思路排查先把报错中提到的.so文件名记住用ldconfig -p | grep 关键字查看系统里有没有对应库缺了直接补。4.2 安装成功但 torch.cuda.is_available() 一直是 False这个问题最隐蔽。表面上看 torch 装的是 GPU 版本但运行时依然检测不到显卡。先按顺序排查确认nvidia-smi能正常输出驱动是否在工作。确认你当前激活的 Python 环境是 conda 里的 genesis 环境而不是系统环境。确认 torch 是从 PyTorch 指定源安装的而不是默认 PyPI。如果驱动正常但还是 False多半是 torch 安装成了 CPU 版本。再跑一次python -c import torch; print(torch.__version__)注意看版本号里有没有cu字样。比如2.1.0cu121说明是 CUDA 版本如果只有2.1.0那很可能就是 CPU 版。解决办法是回到第 3.2 节卸载重装。提示在 Ubuntu 20.04 上如果你用的是 conda Python并装了比较新的 torch偶尔会遇到GLIBCXX_3.4.30 not found的报错。这通常是 conda 环境里的 libstdc 太旧可以执行conda install -c conda-forge libstdcxx-ng升级解决。4.3 源码编译时卡住或者报找不到编译器相关头文件源码安装方式对工具链要求高。如果你执行pip install -e .时看到类似Error: C compiler cannot create executables或者一堆fatal error: bits/cconfig.h file not found大概率是 gcc/g 版本之间的头文件不匹配。一个比较有效的办法是给当前环境配置新版工具链conda activate genesis conda install -y -c conda-forge gcc_linux-64 gxx_linux-64 cmake ninja这里装的工具链只对当前 conda 环境生效不会污染系统全局。装完之后重新进入源码目录再跑一次安装很多时候就能正常编过了。如果还是不行那就老老实实回到发布版安装路线用预编译好的 wheel 绕开本地编译。4.4 无显示器服务器上运行 Demo 黑屏或崩溃如果你是在一台没有显示器的服务器上跑 Genesis调用显示 Viewer 时可能会直接退出或者窗口一闪就没了。原因是这个会话里没有桌面环境。最省事的办法是用xvfb虚拟出一个显示环境sudo apt install -y xvfb xvfb-run -a python your_demo.py这样 Genesis 会把画面渲染到虚拟显示器里不会因为窗口创建失败而中断程序。如果你只是想让程序计算物理结果不需要实时画面也可以在场景初始化时把show_viewer设为 False这样完全不依赖显示器。4.5 import genesis 成功但运行 Demo 时内存不断上涨这类现象通常不是安装问题而是场景里实体太多、物理步进太密导致的资源开销。先用简化场景测试只放一个平面和一个球步进几十次看内存是否稳定。如果简化后正常再逐步往上加实体做到“每次只改一个变量”这样问题能很快定位到具体实体类型或参数上。5. 从安装到跑通第一个仿真一个最小示例5.1 最小 Demo 脚本这里给一个我实际用来验证安装结果的最小脚本。它做的事情很简单创建一个地面在离地半米的位置放一个球然后让球自由落体。import genesis as gs # 有 GPU 就用 GPU没有就用 CPU if hasattr(gs, gpu): gs.init(backendgs.gpu) else: gs.init(backendgs.cuda) scene gs.Scene( simgs.simulator, show_viewerTrue, ) # 一个地面平面 plane scene.add_entity(gs.morphs.Plane()) # 一个半径 0.25 的球放到 (0, 0, 0.5) sphere scene.add_entity( gs.morphs.Sphere( pos(0.0, 0.0, 0.5), radius0.25, ) ) scene.build() for _ in range(500): scene.step()如果一切正常你会看到一个虚拟窗口里有一个球从空中落下在地面上弹几次后逐渐静止。如果你的版本里gs.gpu不存在代码会自动退到gs.cuda。如果两个都没有说明你该检查一下安装包的版本是否太老或者参考最新文档里的初始化写法。这个脚本虽然简单但它已经覆盖了 Genesis 最核心的操作链路初始化后端、创建场景、添加实体、构建场景、步进仿真。后续无论你做什么样的机器人任务都跳不出这几个步骤。5.2 运行性能的几点实测感受我在 20.04 上把仿真步进跑起来之后最明显的感受是第一次scene.build()会有点慢因为要编译底层着色器、加载粗粒度模型资源这是正常现象不是卡死。建议你在scene.build()前后各打一条日志不然容易误以为是程序没响应。另外你不一定每次都要让 Viewer 弹出来。如果你只关心数值结果可以把show_viewer设为 False。这样能省掉渲染相关的性能开销。批量跑数据时尤其明显之前我为了采集训练数据开了一晚上批量渲染 Viewer 不开的情况下速度至少快了一半以上。5.3 把整套安装固化成一个脚本“装一遍成功”不等于“永远成功”。我经常需要在不同机器上复现同样的环境所以会把整套安装流程固化成一个 shell 脚本。这样下次换机器时只要跑一遍就能恢复。#!/usr/bin/env bash set -euo pipefail # 系统依赖 sudo apt update sudo apt install -y build-essential git wget curl cmake ninja-build \ libgl1 libglib2.0-0 libegl1 libxrender1 libxext6 xvfb # 创建 conda 环境 conda create -n genesis python3.10 -y conda run -n genesis pip install --upgrade pip # 安装 GPU 版 PyTorch按你自己的 CUDA 版本切换 conda run -n genesis pip install torch torchvision \ --index-url https://download.pytorch.org/whl/cu121 # 安装 Genesis conda run -n genesis pip install genesis-world echo Genesis install completed. Run: conda activate genesis这里用conda run -n genesis的好处是即使当前 shell 没有激活 genesis 环境也能在当前环境外安装到指定 conda 环境里非常适合写自动化脚本。脚本里记得根据自己的显卡 CUDA 版本改 torch 安装源无显卡的机器可以直接把 torch 改成 CPU 安装方式。写完之后执行bash install_genesis.sh。如果中间断了重新执行也不会重复安装太多东西因为 apt 和 conda 都有缓存机制。我个人在装完这一整套之后还习惯把用到的验证命令整理成一个小文件保存下来比如检测nvidia-smi、torch.cuda.is_available()、import genesis这几项。以后机器被重装或者换了新环境先跑一遍验证心里就踏实了。最后再分享一个经验如果条件允许尽量保持系统整洁。别同时开多个虚拟环境又互相切换着装 torch。torch 和 genesis 安装在哪个环境运行脚本时就必须在哪个环境不然很容易出现“import genesis 报错后面检查发现是 torch 版本串了”的奇葩问题。做好环境隔离你已经解决了安装路上最难的一半。