1. 为什么 Isaac Sim 的环境配置值得单独写一篇如果你最近在折腾机器人仿真、具身智能或者强化学习相关的项目大概率绕不开 NVIDIA 的 Isaac Sim 和 Isaac Lab 这两个工具。Isaac Sim 是基于 Omniverse 平台构建的高保真物理仿真器能跑刚体、柔体、流体、传感器仿真还自带 RTX 光线追踪渲染Isaac Lab 则是架在 Isaac Sim 之上的机器人学习框架专门为强化学习、模仿学习、Sim2Real 这类任务做了封装。两者配合起来基本就是目前做机器人学习最主流的仿真方案之一。但问题也恰恰出在这里。这套工具链对环境的挑剔程度在我用过的仿真软件里算是排得上号的。Ubuntu 20.04 虽然是官方明确支持的版本可实际操作中你会遇到显卡驱动版本不匹配、CUDA 和 PyTorch 版本打架、Python 环境被系统自带版本污染、Omniverse 启动卡在加载界面、Isaac Lab 装完 import 报错等等一系列问题。更麻烦的是很多报错信息非常隐晦网上搜到的答案又往往是针对旧版本的照抄反而会把环境搞得更乱。这篇内容就是把我自己在 Ubuntu 20.04 上反复重装、踩坑、回滚、再重装的过程整理出来。目标很明确让你从一台干净的 Ubuntu 20.04 机器出发一步步把 Isaac Sim 和 Isaac Lab 跑起来中间遇到常见报错能自己定位。适合刚接触这套工具链的新手也适合装了一半卡住、想找排查思路的人。我不会只给你一堆命令而是把每一步为什么这么做、参数为什么这么选讲清楚这样你遇到变体情况时能自己判断。2. 装之前必须想清楚的几件事硬件与系统前提2.1 显卡和驱动是硬门槛不是建议Isaac Sim 对显卡的要求不是能亮机就行。它依赖 RTX 系列的 GPU因为要用到 RT Core 做光线追踪、Tensor Core 做 DLSS 和部分 AI 加速。官方推荐 RTX 3070 及以上显存至少 8GB实际跑复杂场景建议 12GB 以上。我用过 RTX 3060 6GB 的机器简单场景能跑但一加载带多个传感器的机器人模型就开始掉帧甚至爆显存。驱动这块是最容易出问题的。Ubuntu 20.04 自带的 nouveau 开源驱动必须换掉换成 NVIDIA 官方驱动。版本上Isaac Sim 不同版本对驱动最低要求不一样比如 Isaac Sim 4.x 一般要求 535 以上的驱动。你可以用下面这条命令先看看当前驱动情况nvidia-smi如果这条命令报command not found说明驱动根本没装或者没装对。如果输出了表格重点看右上角的 Driver Version 和 CUDA Version。注意这里的 CUDA Version 是驱动支持的最高 CUDA 版本不是你系统里装的 CUDA 版本很多人会搞混这一点。安装驱动我推荐用 Ubuntu 的附加驱动图形界面或者命令行ubuntu-drivers devices sudo ubuntu-drivers autoinstall装完重启再跑nvidia-smi确认。这里有个坑如果你之前装过 CUDA Toolkit 自带的驱动可能会和 apt 装的驱动冲突导致开机黑屏或者循环登录。遇到这种情况进 recovery 模式用sudo apt purge nvidia-*清干净再重装。2.2 系统版本和内核的隐性影响Ubuntu 20.04 的默认内核是 5.4这个内核和较新的 NVIDIA 驱动配合一般没问题。但如果你升级过内核到 5.15 或更高某些驱动版本可能会出现编译 DKMS 模块失败的情况。判断方法很简单uname -r如果驱动装完nvidia-smi还是报错八成是内核模块没编译进去。这时候要么回退内核要么换一个和当前内核兼容的驱动版本。我的经验是做仿真这类对稳定性要求高的活别追新内核5.4 或 5.15 这两个 LTS 内核最稳。另外Ubuntu 20.04 默认的 Python 是 3.8。Isaac Sim 4.x 要求 Python 3.10Isaac Lab 也跟着要求 3.10。这就意味着你不能直接用系统 Python必须用 conda 或者单独编译一个 3.10 环境。这一点后面会详细讲但你现在就要有这个意识系统 Python 千万别动动了系统工具可能就崩了。2.3 磁盘空间和文件系统Isaac Sim 的安装包解压后动辄十几个 GB加上 Omniverse 的缓存、Isaac Lab 的依赖、各种资产包预留 100GB 是比较稳妥的。我见过有人装到一半提示空间不足结果清理起来很麻烦。文件系统建议 ext4如果你用的是 NTFS 挂载的分区权限问题会让你怀疑人生。还有一点Isaac Sim 的资产缓存默认放在~/.cache/ov和~/.local/share/ov下面这些目录会随着你使用不断膨胀。如果你的 home 分区不大建议提前把这两个目录软链接到大分区上mkdir -p /data/ov_cache ln -s /data/ov_cache ~/.cache/ov这个操作看起来不起眼但能帮你省掉后面磁盘满了导致仿真崩溃的排查时间。3. 基础依赖的安装顺序与版本锁定3.1 换源和系统更新别跳过这一步Ubuntu 20.04 默认的软件源在国内访问速度堪忧装依赖时经常超时。换源这件事网上教程很多核心就是改/etc/apt/sources.list。我一般用清华或者阿里的源改完执行sudo apt update sudo apt upgrade -y这里要注意upgrade可能会顺带升级内核如果你不想动内核用sudo apt-mark hold linux-image-generic linux-headers-generic先锁住。升级完重启一次确保系统处于干净状态。3.2 编译工具链和基础库Isaac Sim 和 Isaac Lab 在安装过程中会编译一些扩展所以 build-essential、cmake、git 这些是必须的sudo apt install -y build-essential cmake git wget curl sudo apt install -y libgl1-mesa-glx libglib2.0-0 libsm6 libxext6 libxrender-dev后面这几个 lib 是图形相关的缺了会导致 Omniverse 启动时报 libGL error 或者 cannot open shared object file。这类报错看起来吓人其实补上对应的库就好。还有一个容易被忽略的是libssl和libffi的开发包Python 编译和某些 pip 包会用到sudo apt install -y libssl-dev libffi-dev libbz2-dev libreadline-dev libsqlite3-dev3.3 用 conda 隔离 Python 3.10 环境前面说了系统 Python 3.8 不能动。最省事的方案是装 Miniconda然后建一个 Python 3.10 的环境。下载 Miniconda 安装脚本wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装过程中会让你选择是否初始化 conda 到 shell选 yes。装完重开终端然后建环境conda create -n isaaclab python3.10 -y conda activate isaaclab为什么是 3.10 而不是 3.11 或 3.12因为 Isaac Sim 4.x 和 Isaac Lab 官方明确测试过的是 3.10用其他版本可能在装某些 wheel 包时找不到对应版本。这种官方测过的版本别自作聪明去换。建好环境后建议把 pip 也升级一下并设置国内镜像加速pip install --upgrade pip pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple4. Isaac Sim 的安装方式选择与实操4.1 三种安装方式的取舍Isaac Sim 目前主要有三种安装方式Omniverse Launcher 图形化安装、pip 安装、以及下载独立压缩包。这三种方式各有适用场景选错了后面会很别扭。Omniverse Launcher 是最官方的方式好处是能自动管理版本、更新方便坏处是它本身是个 Electron 应用在 Ubuntu 20.04 上偶尔会有界面渲染问题而且它会把 Isaac Sim 装到固定的目录结构里你想自定义路径比较麻烦。pip 安装是 Isaac Sim 4.x 之后官方推的方式直接pip install isaacsim就能装适合喜欢命令行、想集成到现有 Python 环境的人。但 pip 安装的版本对系统依赖的处理不如 Launcher 完善某些扩展可能缺失。独立压缩包是最可控的方式下载一个 zip解压到任意目录运行里面的脚本就能启动。缺点是更新要手动下载新包。我个人推荐新手用 Omniverse Launcher因为它把驱动检查、依赖安装这些脏活都包了出问题也容易定位。如果你已经有一套成熟的 conda 工作流pip 安装更顺手。4.2 用 Omniverse Launcher 安装的完整流程先从 NVIDIA 官网下载 Omniverse Launcher 的 AppImage 文件。下载完给执行权限chmod x omniverse-launcher-linux.AppImage ./omniverse-launcher-linux.AppImage第一次启动会要求登录 NVIDIA 账号没有的话注册一个。登录后在 EXCHANGE 标签页搜索 Isaac Sim选择版本安装。这里版本选择有讲究如果你要用 Isaac Lab得看 Isaac Lab 对应支持的 Isaac Sim 版本。比如 Isaac Lab 1.x 通常对应 Isaac Sim 4.0 或 4.1装错了版本后面 import 会报 API 不匹配。安装路径默认在~/.local/share/ov/pkg/isaac-sim-version。安装完成后Launcher 里会有 Launch 按钮。但先别急着点我们还要处理几个环境变量。4.3 环境变量配置让 Isaac Sim 能被找到Isaac Sim 启动依赖一些环境变量最省事的做法是在~/.bashrc里加一段export ISAACSIM_PATH$HOME/.local/share/ov/pkg/isaac-sim-4.1.0 export ISAACSIM_PYTHON_EXE$ISAACSIM_PATH/python.sh注意路径里的版本号要和你实际装的一致。加完source ~/.bashrc生效。这样你在任何目录下都能用$ISAACSIM_PATH引用安装目录后面配 Isaac Lab 时会用到。还有一个关键点Isaac Sim 自带的 Python 是它自己打包的不是你 conda 环境里的 Python。这一点非常重要很多人搞混。Isaac Sim 的python.sh会启动它内置的解释器而 Isaac Lab 需要装到你自己的 conda 环境里然后通过 Isaac Sim 的 Python 去调用。理解这个关系后面很多报错就顺了。4.4 首次启动的验证与常见卡顿第一次启动 Isaac Sim 会比较慢因为它要下载一堆扩展和资产。如果卡在 Loading Omniverse Kit 超过十分钟先检查网络再检查磁盘空间。如果卡在 RTX loading 或者直接黑屏多半是驱动问题回第 2 节检查nvidia-smi。启动成功后你会看到一个空的 3D 场景。这时候可以打开 Window Examples Robotics Examples随便加载一个机器人模型试试。如果能正常显示并且能拖动视角说明基础环境没问题。这里分享一个实测技巧首次启动前先把~/.nvidia-omniverse/logs目录清空这样如果启动失败日志里只有本次的记录排查起来干净。日志文件是定位问题的第一手资料比网上搜的答案靠谱得多。5. Isaac Lab 的部署与两者联动5.1 从 GitHub 克隆并安装Isaac Lab 的代码在 GitHub 上开源直接克隆cd ~ git clone https://github.com/isaac-sim/IsaacLab.git cd IsaacLab克隆完先别急着装看一下仓库根目录的README或者VERSION文件确认它支持的 Isaac Sim 版本和你装的一致。版本不匹配是 Isaac Lab 报错的头号原因。安装分两步。第一步用 Isaac Sim 的 Python 装 Isaac Lab 的核心包$ISAACSIM_PATH/python.sh -m pip install -e source/isaaclab这里的-e是 editable 模式方便你改代码后不用重装。第二步装扩展包比如isaaclab_assets、isaaclab_tasks$ISAACSIM_PATH/python.sh -m pip install -e source/isaaclab_assets $ISAACSIM_PATH/python.sh -m pip install -e source/isaaclab_tasks注意这里用的是$ISAACSIM_PATH/python.sh而不是你 conda 环境的 python。因为 Isaac Lab 依赖 Isaac Sim 提供的omni模块只有 Isaac Sim 的 Python 才有这些模块。5.2 验证安装跑一个官方示例装完后跑一个最简单的训练示例验证$ISAACSIM_PATH/python.sh scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --headless--headless表示不开图形界面纯后台跑适合服务器环境。如果这条命令能跑起来并开始输出训练日志说明 Isaac Lab 装好了。如果报ModuleNotFoundError: No module named isaaclab说明第一步没装成功检查是不是在正确的目录下执行的。如果报ImportError: libpython3.10.so.1.0: cannot open shared object file这是 conda 环境的库路径没被 Isaac Sim 的 Python 找到。解决办法是在~/.bashrc里加export LD_LIBRARY_PATH$CONDA_PREFIX/lib:$LD_LIBRARY_PATH这个报错我遇到过好几次本质是 Isaac Sim 的 Python 和 conda 的 Python 共享库路径不一致导致的。5.3 图形界面模式下的注意事项去掉--headless就能开图形界面看训练过程。但图形模式下对显存要求更高而且如果你是通过 SSH 连的服务器需要配置 X11 转发或者用 VNC。X11 转发跑 Isaac Sim 基本不可用延迟太高建议用 VNC 或者直接在本地机器上跑。还有一个细节图形模式下 Isaac Sim 会占用一个显示端口如果你同时开了其他 3D 应用可能会冲突。我一般训练时用 headless需要看效果时再单独开图形界面加载 checkpoint。6. 那些让人抓狂的报错完整排查链路6.1 报错一驱动版本不满足最低要求现象启动 Isaac Sim 时弹窗提示 Your GPU driver version is too old或者直接闪退。排查过程先跑nvidia-smi看 Driver Version。假设显示 470而 Isaac Sim 4.1 要求 535 以上那就是版本低了。但别急着直接装最新驱动先确认你的 GPU 型号支持哪个驱动分支。老卡比如 GTX 10 系可能不支持最新的 535 驱动。解决用ubuntu-drivers devices看推荐的驱动版本选一个满足 Isaac Sim 要求且支持你显卡的。装完重启再验证。如果装完nvidia-smi报 Failed to initialize NVML多半是驱动和内核不匹配检查dmesg | grep nvidia看具体错误。6.2 报错二Python 版本冲突导致的 import 失败现象在 conda 环境里import isaaclab报错提示某个模块找不到或者版本不对。排查过程先确认你当前在哪个 Python 环境which python python --version如果显示的是系统 Python 3.8说明 conda 环境没激活。如果显示 3.10 但还是报错检查是不是用错了 Python。Isaac Lab 必须用 Isaac Sim 的python.sh来跑不是 conda 的 python。解决养成习惯跑 Isaac Lab 相关命令前先echo $ISAACSIM_PATH确认变量存在然后用$ISAACSIM_PATH/python.sh而不是python。6.3 报错三Omniverse 缓存损坏导致启动卡死现象之前能正常启动某次突然卡在加载界面日志里反复出现某个扩展加载失败。排查过程看~/.nvidia-omniverse/logs/下最新的日志找到报错的扩展名。常见的是omni.isaac.core或者某个渲染扩展加载失败。解决清空缓存目录重试rm -rf ~/.cache/ov/* rm -rf ~/.local/share/ov/data/*注意别删~/.local/share/ov/pkg那是安装目录。清完缓存重新启动Isaac Sim 会重新下载缺失的扩展。这个操作相当于重置能解决大部分因为缓存不一致导致的问题。6.4 报错四Isaac Lab 训练时显存溢出现象训练脚本跑了几步后报 CUDA out of memory。排查过程Isaac Sim 本身占显存就不少加上 Isaac Lab 的并行环境显存消耗是成倍增长的。用nvidia-smi实时看显存占用确认是环境数量太多还是模型太大。解决减少并行环境数量。在 Isaac Lab 的任务配置里找num_envs参数从默认的几千降到几百试试。另外可以开--headless模式省下图形渲染的显存。如果还是不够考虑用更小的机器人模型或者降低仿真精度。6.5 报错五libGL 相关错误现象启动时报libGL error: MESA-LOADER: failed to open swrast或者cannot open shared object file: libGL.so.1。排查过程这是图形库缺失或冲突。Ubuntu 20.04 上如果装了多个版本的 Mesa 库容易出这个问题。解决重装相关库sudo apt install --reinstall libgl1-mesa-glx libgl1-mesa-dri如果还不行检查是不是 conda 环境里也装了 Mesa 库导致路径冲突。用ldd命令看具体是哪个库找不到ldd $ISAACSIM_PATH/kit/kit | grep not found这条命令能列出所有缺失的库比盲目搜索高效得多。7. 让环境更稳的几个实操习惯7.1 用脚本固化环境变量每次开新终端都要手动设环境变量太麻烦而且容易忘。我习惯写一个setup_isaac.sh脚本#!/bin/bash export ISAACSIM_PATH$HOME/.local/share/ov/pkg/isaac-sim-4.1.0 export ISAACSIM_PYTHON_EXE$ISAACSIM_PATH/python.sh export LD_LIBRARY_PATH$CONDA_PREFIX/lib:$LD_LIBRARY_PATH conda activate isaaclab每次开工前source setup_isaac.sh环境一步到位。这个脚本还能提交到 git换机器时直接复用。7.2 版本记录别相信自己的记忆Isaac Sim、Isaac Lab、驱动、CUDA、Python 这几个版本之间的对应关系很微妙今天装好了过两个月回来可能就忘了当时装的哪个版本。我建议在项目根目录放一个ENV_VERSIONS.md记录组件版本备注Ubuntu20.04.6 LTS内核 5.15NVIDIA Driver535.154.05Isaac Sim4.1.0Omniverse Launcher 安装Isaac Lab1.2.0git commit abc123Python3.10.13conda 环境 isaaclab这张表在排查问题时价值极高尤其是多人协作时能快速对齐环境。7.3 备份 conda 环境conda 环境装好后导出成 yaml 文件conda env export -n isaaclab isaaclab_env.yaml这样即使环境被搞坏也能快速重建。不过要注意Isaac Sim 相关的包不在 conda 里yaml 只能恢复 Python 层的依赖Isaac Sim 本身还是要重新装。7.4 日志是你的朋友遇到任何报错第一反应应该是看日志而不是搜报错信息。Isaac Sim 的日志在~/.nvidia-omniverse/logs/Isaac Lab 的日志在运行目录下的logs/文件夹。日志里的报错堆栈比弹窗信息详细得多往往直接指向问题根源。我踩过的坑里至少一半是靠读日志自己解决的搜出来的答案反而把我带偏过。8. 关于这套环境的一些个人体会折腾 Isaac Sim 和 Isaac Lab 这段时间最大的感受是这套工具链的复杂度不在它本身而在它依赖的整个生态。显卡驱动、CUDA、Python、Omniverse、Isaac Lab每一层都有自己的版本要求任何一层不匹配都会在某个意想不到的地方爆出来。所以配置环境时耐心比技术更重要按部就班把每一层验证通过比急着跑 demo 要省时间。另外官方文档虽然全但更新速度跟不上版本迭代有些步骤已经过时了。遇到文档和实际不符时以实际报错和日志为准。社区里 Isaac Sim 的论坛和 GitHub issue 质量不错搜问题时加上具体版本号能过滤掉很多无效信息。最后说一个我自己的习惯每装完一个关键组件就立刻跑一个最小验证确认这层没问题再往下走。比如装完驱动跑nvidia-smi装完 Isaac Sim 跑一个空场景装完 Isaac Lab 跑一个 Cartpole 训练。这样出问题时你能确定是哪一层引入的排查范围大大缩小。这个习惯帮我省下了大量从头重装的时间。