安装排障手册#
学习目标
用报错里的关键句在本页找到对应条目，按"现象 / 原因 / 解法"处理
知道 Kit 日志和 Isaac Lab 日志在哪、先看哪一个
向官方提 issue 时一次附齐需要的信息
前置知识
1.4 安装 Isaac Sim 5.1 + Isaac Lab 2.3.2（pip 方式）：本页条目默认按那一页的方式安装
怎么用这一页#
这一节回答：报错了，怎么在这一页里找？
复制报错里最有辨识度的一句（通常是 ERROR、Error 后面那句，或 Traceback 最后一行），用浏览器的页内查找（Ctrl+F）或站内搜索。每条的三级标题就是报错原文；没有固定报错文字的问题，标题写现象。
每条固定三行：现象（你看到了什么）、原因、解法，最后是来源。标"本站实测"的条目，都在本站的 Isaac Sim 5.1.0 + Isaac Lab 2.3.2 环境（Ubuntu 22.04、RTX 5070、驱动 580.178.04）中复现过[1]。
本页是参考页，会持续追加条目。
通用排障顺序#
这一节回答：遇到没见过的报错，按什么顺序查？
往上翻，找第一个真正的错误。 Isaac Sim 崩溃时，终端末尾常常是一大串
Exception ignored in ... __del__和Segmentation fault，它们是退出时的连带报错，真正的原因在更上面[2]。见下文崩溃时满屏__del__报错。看日志文件。 终端默认只打印
WARN及以上级别，完整信息在日志文件里[3]。日志路径在终端开头几行就会打印出来，搜Logging to file即可。提高日志级别再跑一次。 在命令后加
--info或--verbose[3]。缩到最小复现。 先跑官方的
scripts/tutorials/00_sim/create_empty.py --headless[4]，或本站的verify_install.py。它们能跑通，说明安装没问题，问题在你的脚本或资产；它们也跑不通，就回到安装阶段的条目逐个排除。检查环境变量。 打印
PYTHONPATH、CONDA_PREFIX、VIRTUAL_ENV，确认用的是你以为的那个 Python 环境（which python）。
日志 |
pip 安装时的位置 |
内容 |
|---|---|---|
Kit 日志 |
|
Isaac Sim 各扩展的完整日志，含 GPU、驱动版本表 |
Isaac Lab 日志 |
|
Isaac Lab 自身的日志 |
训练输出 |
|
训练脚本的 checkpoint 与 TensorBoard 数据 |
表 1：日志位置。前两行为本站实测：启动时终端分别打印 [Info] [carb] Logging to file: 和 [INFO][IsaacLab]: Logging to file:，以终端打印的为准。二进制（workstation）安装的 Kit 日志在 ~/.nvidia-omniverse/logs/Kit/Isaac-Sim[5]。
安装阶段#
这一节回答：pip install 和 ./isaaclab.sh --install 时的报错。
ERROR: No matching distribution found for isaacsim==5.1.0#
现象：
pip install "isaacsim[all,extscache]==5.1.0"失败，上一行列出的可用版本最高只到4.5.0.0。原因：当前环境的 Python 不是 3.11。Isaac Sim 5.1 的 pip 包只提供 Python 3.11 的版本[6]；用 3.10 时 pip 只能看到 4.x 的版本（4.5 要求 3.10）。
解法：
python --version确认版本，按 1.4 第一步 用python=3.11重建环境。Ubuntu 22.04 自带 3.10，24.04 自带 3.12[7]，都不能直接用。
来源：本站实测（系统 Python 3.10.12 下执行 pip download "isaacsim==5.1.0"，输出如标题，可用版本列表为 4.0.0.0 至 4.5.0.0）；PyPI[6]。
GLIBC 版本低于 2.35（Ubuntu 20.04 等）#
现象：在较老的 Linux 发行版上 pip 找不到
isaacsim5.1.0，报错与上一条相同；或其他依赖报GLIBC_2.xx not found。原因：pip 安装的 Isaac Sim 要求 GLIBC 2.35 及以上，Ubuntu 20.04 默认是 2.31[8]。本站查看
isaacsim5.1.0.0 的 wheel 标签为manylinux_2_35_x86_64，即 pip 在 GLIBC 低于 2.35 的系统上不会选中它（推断：依据 wheel 标签规则，未在 20.04 上实测）。解法：
ldd --version查看版本。低于 2.35 时改用二进制安装或容器[8]，见 1.6 容器化 与 1.7 安装方式对比。
来源：Isaac Lab pip 安装页[8]；wheel 标签为本站实测（isaacsim-5.1.0.0.dist-info/WHEEL）。
[ERROR] Unable to find any Python executable at path: '.../_isaac_sim/python.sh'#
现象：运行
./isaaclab.sh --install或./isaaclab.sh -p ...时立即退出，下面列出三条可能原因。原因：
isaaclab.sh依次在CONDA_PREFIX、VIRTUAL_ENV、仓库下的_isaac_sim/python.sh中找 Python[9]。pip 安装时出现这个错，几乎都是因为当前终端没有激活环境。解法：先
conda activate env_isaaclab或source env_isaaclab/bin/activate，再运行isaaclab.sh。新开的终端要重新激活。
来源：本站实测（未激活环境时运行 ./isaaclab.sh -p -c "print(1)"，输出如标题）；isaaclab.sh 源码[9]。
[ERROR] Unable to find the Isaac Sim directory#
现象：
isaaclab.sh报这一句，并提示Isaac Sim pip package 'isaacsim-rl' is not installed等三条可能原因。原因：
isaaclab.sh先找仓库下的_isaac_sim软链接，找不到时再检查当前环境是否装了 pip 包isaacsim-rl（isaacsim[all]会带上它）[10]。两者都没有就报错。解法：pip 安装的，确认已激活环境并且
pip list | grep isaacsim-rl有输出；二进制安装的，按官方步骤在 Isaac Lab 仓库下建_isaac_sim软链接指向 Isaac Sim 安装目录[11]。
来源：isaaclab.sh 源码[10]。
ModuleNotFoundError: No module named 'omni'#
现象：执行
from omni.isaac.kit import SimulationApp（或其他omni.*导入）时报错。网上的旧教程常这样写。原因：pip 安装时，
omni.*这些模块的路径由import isaacsim注册进来；不先导入isaacsim，Python 找不到它们。另外omni.isaac.*在 5.x 已弃用，只保留兼容，计划在 6.0 移除（D-009）[12]。解法：新代码直接写
from isaacsim import SimulationApp。运行旧代码时，在第一行加import isaacsim，之后omni.isaac.kit可以导入，但会打印弃用警告。用 Isaac Lab 时，通过AppLauncher启动即可，不用自己处理。
来源：本站实测（不先 import isaacsim 时报 No module named 'omni'；先导入后能导入，并打印 omni.isaac.kit has been deprecated in favor of isaacsim.simulation_app）。
ModuleNotFoundError: No module named 'isaaclab'#
现象：
pip list里明明有isaaclab，导入时却报这一句；如果当前目录下正好有名为isaaclab的文件夹（如仓库的source/，或/tmp：Isaac Lab 把日志写在/tmp/isaaclab/），则import isaaclab不报错，但isaaclab.__file__为None，下一步报No module named 'isaaclab.app'。原因：
./isaaclab.sh --install用 editable 方式安装，环境里记录的是源码的绝对路径。移动或删除 Isaac Lab 仓库后，这个路径失效，只剩安装记录（dist-info）还在[1]。当前目录下有同名文件夹时，它被当作空的命名空间包（namespace package）导入，于是出现__file__为None。解法：在仓库的新位置、激活环境后重新运行
./isaaclab.sh --install。检查方法：python -c "import isaaclab; print(isaaclab.__file__)"应打印仓库内的真实路径。
来源：本站实测（校验环境中仓库移动过；在 IsaacLab/source/ 与 /tmp 下得到命名空间包，在其他目录下报 No module named 'isaaclab'）[1]。
装了 ROS 2 的机器上，导入时版本冲突或报奇怪的错误#
现象：
python -c "import sys; print(sys.path)"里出现/opt/ros/humble/...；导入 numpy 等包时版本不对，或出现与 ROS 包相关的报错。原因：
~/.bashrc里source /opt/ros/humble/setup.bash设置了PYTHONPATH，这些路径排在环境自己的包之前，ROS 2 自带的 Python 包混了进来[1]。解法：在跑 Isaac Lab 的终端里
unset PYTHONPATH，或用env -u PYTHONPATH python ...启动。要同时用 ROS 2 时，见 3.10 ROS 2 Bridge。
来源：本站实测[1]。
首次启动#
这一节回答：装完第一次运行时遇到的问题。
Do you accept the EULA? (Yes/No): 卡住，或 EOFError: EOF when reading a line#
现象：第一次
import isaacsim时停在 EULA 提示；在后台、CI、容器或nohup里运行时没人回答，看起来像卡死；标准输入被关闭时直接报EOFError。原因：Isaac Sim 首次导入时要求确认 EULA[13]。确认结果写进安装目录下的
isaacsim/kit/EULA_ACCEPTED文件，所以每个新环境都会再问一次（本站查看已安装包的isaacsim/kit/kit_app.py得知）。解法：设置环境变量
OMNI_KIT_ACCEPT_EULA=YES（Y、1也可以）[13]，例如export OMNI_KIT_ACCEPT_EULA=YES，或交互运行一次回答Yes。
来源：Isaac Sim pip 安装页[13]；EOFError 为本站实测（关闭标准输入后调用 EULA 检查）。
第一次启动很久没有输出，像是卡死#
首次启动时下载扩展失败（离线环境、没装 extscache）#
现象：在无法访问外网的机器上首次启动失败，日志里有扩展无法解析或下载的错误。
原因：Isaac Sim 依赖的 Omniverse 扩展要么随
[extscache]预先装好，要么在首次启动时从扩展注册中心下载[13][14]。安装时漏了extscache，又没有网络，就拿不到扩展（推断：依据上述两处说明，本站未在离线环境实测，报错原文暂缺）。解法：安装时写全
isaacsim[all,extscache]==5.1.0，见 1.4 第二步。已经装好的环境可以补装pip install "isaacsim[extscache]==5.1.0" --extra-index-url https://pypi.nvidia.com。
DISPLAY environment variable is not set, running in headless mode / GLFW initialization failed#
现象：通过 SSH 或在没有桌面的服务器上以 GUI 模式启动，终端出现这两句警告，但程序继续运行，没有窗口。
原因：没有
DISPLAY时，SimulationApp自动加上--no-window改为 headless 运行；窗口库 GLFW 初始化失败的警告随之出现，属于预期行为，不影响仿真[16]。解法：服务器上直接加
--headless运行，警告就不再出现。需要看画面时，在有桌面的机器上运行，或用直播流（livestream）远程查看，见 7.1 headless 与远程运行。
来源：本站实测（去掉 DISPLAY 后以 headless=False 启动，程序正常运行）；SimulationApp 源码[16]。
驱动过旧：启动失败、黑屏或崩溃#
现象：启动阶段崩溃、黑屏，或渲染相关扩展报错。没有统一的报错原文。
原因：NVIDIA 驱动低于推荐版本。Isaac Lab 2.3.2 推荐 Linux 驱动 580.65.06 或更新[17]。
解法：先查驱动版本：
nvidia-smi，或在 Kit 日志里搜Driver Version，日志中有一张 GPU 与驱动版本表（本站实测）。低于推荐值时，官方建议从 Unix Driver Archive 安装最新的**生产分支（production branch）**驱动[17][18]。版本对照见 1.1 版本兼容矩阵。
运行阶段#
这一节回答：安装没问题，但跑起来出错或退不出去。
torch.OutOfMemoryError: CUDA out of memory#
PhysX error: the application need to increase the PxgDynamicsMemoryConfig::foundLostPairsCapacity#
现象：GPU 仿真运行一段时间后报这一句（有时是其他
...Capacity参数），之后出现穿模或接触丢失。原因：GPU 物理的缓冲区只在仿真开始时按配置分配一次，不会自动增长；碰撞对数量（常随
num_envs增加）超过缓冲区大小就会报错[21]。解法：把报错里建议的数值写进
PhysxCfg对应的gpu_*_capacity参数，例如sim_cfg.physx.gpu_found_lost_pairs_capacity = 4096[21]。
来源：Isaac Lab 排障页[21]。
Exception ignored in: ... __del__ / TypeError: 'NoneType' object is not callable#
现象：脚本出错后，终端末尾是一大串
Exception ignored in与NoneType报错，最后是Segmentation fault (core dumped)。原因：这些是 Python 解释器退出时销毁 Isaac Sim 对象引起的连带报错，不是真正的原因[2]。
解法：往上翻，找到第一段完整的
Traceback，那里才是出错的地方[2]。
来源：Isaac Lab 排障页[2]。
自己写的脚本退出时卡住，simulation_app.close() 不返回#
现象：脚本逻辑已经跑完，进程却一直不退出，CPU 占满。
原因：脚本自己创建了
SimulationContext，在它还存在时调用simulation_app.close()会卡住。Isaac Lab 的环境类在close()中会先清理仿真上下文[22]。解法：在
simulation_app.close()之前调用sim.clear_all_callbacks()和sim.clear_instance()；用gym.make创建的环境，先调用env.close()。完整写法见本站示例verify_install.py。
来源：本站实测（编写 1.4 验证脚本时复现并修复）；Isaac Lab 源码[22]。
timeout 或 kill 结束不了 Isaac Sim 进程#
现象：用
timeout 600 python ...限时运行，到时间后进程仍在；kill <pid>无效。原因：Kit 进程收到 SIGTERM 后不退出（本站实测：
create_empty.py打印Setup complete后发 SIGTERM，60 秒后进程仍在，发 SIGKILL 才结束）。具体机制未查到官方说明（推断：Kit 自己处理了该信号）。解法：无人值守运行时用
timeout -s KILL <秒数> python ...，手动结束用kill -9 <pid>。同时设PYTHONUNBUFFERED=1，避免被强杀时丢失尚未刷新的输出。
来源：本站实测。
如何提问#
这一节回答：本页没找到，要向官方求助时附哪些信息？
先搜一遍 Isaac Lab 的 GitHub Issues 和 Discussions，很多问题已有人问过。提新 issue 时附上：
项 |
怎么获取 |
|---|---|
Isaac Sim 版本 |
|
Isaac Lab 版本与 commit |
仓库下 |
安装方式 |
pip / 二进制 / 容器；conda / uv / venv |
操作系统与 GLIBC |
|
GPU 与驱动 |
|
Python 与 PyTorch |
|
最小复现命令 |
能在干净环境重现的一条命令，最好基于官方示例脚本 |
完整报错 |
终端输出从第一个 |
Kit 日志 |
见表 1，官方要求报告问题时附上[3] |
表 2：提 issue 时的信息清单。
常见坑#
本页每一条都是坑，这里不再重复。安装流程中的注意事项见 1.4 的"常见坑"。
延伸阅读#
版本说明#
本页条目针对 Isaac Sim 5.1.0 + Isaac Lab 2.3.2 的 pip 安装。Isaac Sim 6.1 + Isaac Lab 3.0 要求 Python 3.12，本页中与 Python 版本、omni.isaac.* 导入相关的条目在 3.0 上情况不同，见 1.5 安装 Isaac Sim 6.1 + Isaac Lab 3.0-EA 与 8.1 3.0 改了什么、为什么改。