SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsisaac-sim-headless-deployment

isaac-sim-headless-deployment

Deployment & operations

View repository

Updated 10-16 11:05

About this skill

Isaac Sim Headless Usage (--no-window)

Purpose

Launch Isaac Sim without a window for batch simulation, automated data generation, and server workloads using supported CLI flags and SimulationApp patterns.

Prerequisites

  • Built Isaac Sim ($ISAAC_SIM_DIR or _build/linux-x86_64/release).
  • NVIDIA GPU with a current driver (nvidia-smi).
  • Shell env contract from isaac-sim-orchestrator: $ISAAC_SIM_DIR, $ISAAC_LAB_DIR, $WORKSPACE_DIR.

Limitations

  • Targets Isaac Sim 6 / Kit 110 unless a section states otherwise.
  • Does not replace official NVIDIA documentation for unsupported edge cases.

Troubleshooting

Error / symptom Cause Solution
Extension or import not found Wrong $ISAAC_SIM_DIR or stale build Point env vars at _build/linux-x86_64/release or rebuild
Black or empty frames Missing lights or non-RTX render mode Add dome/key light; confirm RTX / PathTracing settings
Hang on stage load or first render MDL compile or oversized stage Follow isolation steps in isaac-sim-troubleshooting

This skill covers headless usage of a built or installed Isaac Sim. It does not cover Docker images, container orchestration, or CI/CD wiring — those live with the deployment infrastructure that wraps Isaac Sim, not in this skill.

Available Scripts

Script Purpose Arguments
scripts/batch_simulation.py Headless batch simulation loop for Isaac Sim (Kit 110) see script --help
scripts/ci_physics_nightly.sh CI physics-only nightly runner via python.sh or Kit CLI <test_script.py> [args...]

Running scripts

From agent runtimes that expose skill execution helpers, invoke helpers with run_script():

run_script("scripts/batch_simulation.py", args=["--help"])

From a built Isaac Sim tree, run the same file with ./python.sh (Linux) or python.bat (Windows) from _build/*/release, or execute shell helpers directly when they do not require the simulator.

Launch modes

1. Headed (Default)

./isaac-sim.sh
# Launches isaacsim.exp.full.kit with full UI

2. Headless with Rendering

For headless GPU rendering (generates images without a window):

# Native headless — uses EGL/Vulkan offscreen
./isaac-sim.sh --no-window

# With explicit display (required on some systems)
DISPLAY=:0 ./isaac-sim.sh --no-window

3. Headless No Rendering

For physics-only simulation (no viewport, no rendering):

./isaac-sim.sh --no-window --/app/renderer/enabled=false

4. Python Standalone Scripts

Run simulation logic from a standalone Python script:

./python.sh my_simulation.py
# Uses Isaac Sim's Python environment with all extensions available

The script controls headless behavior via the SimulationApp config (see Batch simulation pattern below) — python.sh does not need a --no-window flag.

5. Kit CLI with Script Execution

# Default — full Isaac Sim experience with rendering enabled
./kit/kit apps/isaacsim.exp.full.kit --exec "my_script.py"

# Headless physics-only batch
./kit/kit apps/isaacsim.exp.full.kit \
    --no-window \
    --/app/renderer/enabled=false \
    --exec "physics_batch.py"

Key CLI Flags

Flag Description
--no-window Disable window creation (headless)
--/app/renderer/enabled=false Disable rendering entirely
--/app/window/width=W Set viewport width
--/app/window/height=H Set viewport height
--/app/settings/fabricDefaultStageFrameHistoryCount=N Frame history for Fabric
--enable EXT_ID Enable specific extension
--ext-folder PATH Add extension search path
--exec SCRIPT Execute script on startup
--no-ros-env Skip ROS 2 auto-sourcing

App Configurations

Config File Use Case
isaacsim.exp.full.kit Full simulation (default)
isaacsim.exp.full.newton.kit Newton physics engine
isaacsim.exp.full.fabric.kit Fabric scene delegate
isaacsim.exp.base.kit Minimal base (faster startup)
isaacsim.exp.base.python.kit Python-only base
isaacsim.exp.base.python.physics.headless.kit Physics-only headless (CI nightly)
isaacsim.exp.base.zero_delay.kit Zero-delay base

CI Physics-Only Nightly Runs

For physics-only nightly CI (no rendering, no window), use the dedicated kit file:

# Kit CLI mode — self-contained headless physics config
./kit/kit apps/isaacsim.exp.base.python.physics.headless.kit \
    --no-window \
    --/app/renderer/enabled=false \
    --exec "test_physics_batch.py"

For standalone Python scripts that bootstrap SimulationApp themselves, use python.sh with renderer-disable flags:

# python.sh mode — flags passed through to Carbonite/Kit settings
./python.sh test_physics_batch.py \
    --/renderer/enabled=false \
    --/app/window/enabled=false \
    --/app/livestream/enabled=false

The kit file (isaacsim.exp.base.python.physics.headless.kit) bakes in:

  • renderer.enabled = false — no GPU rendering subsystem
  • app.window.enabled = false — no window creation
  • app.livestream.enabled = false — no streaming
  • All UI/viewport/manipulator extensions disabled
  • All rendering extensions disabled (omni.hydra.rtx, omni.rtx.*, omni.syntheticdata, omni.replicator.core)
  • Physics-optimal loop settings (rateLimitEnabled = false, manualModeEnabled = true, useFixedTimeStepping = true)

The wrapper script scripts/ci_physics_nightly.sh encapsulates both modes. Set CI_KIT_MODE=1 for Kit CLI, or leave unset for python.sh (default).

Batch Simulation Pattern

The canonical headless bootstrap pattern lives in:

  • source/standalone_examples/api/isaacsim.simulation_app/hello_world.py (minimal)
  • source/standalone_examples/api/isaacsim.simulation_app/load_stage.py (stage open + step loop with --test mode)

For an N-episode batch driver, wrap that bootstrap in a Python for episode in range(N) loop. Use the current APIs:

  • isaacsim.core.experimental.utils.stage for stage open / waiting on load
  • isaacsim.core.simulation_manager.SimulationManager.setup_simulation(dt=..., device=...) to configure physics
  • isaacsim.core.experimental.utils.app (enable_extension, play, stop, update_app) to drive the loop

Skeleton (paraphrased from load_stage.py, adapted for batch):

run_batch_simulation(scene_path, num_episodes, steps_per_episode, dt, device) — headless SimulationApp loop that opens a USD, waits for load, sets up physics, steps, and stops each episode.

See scripts/batch_simulation.py.

Avoid the legacy isaacsim.core.api.World / isaacsim.core.utils.stage paths — they are deprecated in Kit 110.

Migration: see Renaming Extensions for the omni.isaac.* → isaacsim.* map covering omni.isaac.core, omni.isaac.utils, and friends.

Performance Tuning for Batch/Headless

Physics-Only (Fastest)

config = {"headless": True, "renderer": None}
# In step loop:
world.step(render=False)

Throughput: 10-50x real-time depending on scene complexity.

Memory Management

  • Clear stage between episodes: world.clear() + garbage collect
  • Use instanceable assets: make_instanceable: true in config.yaml
  • Monitor GPU memory: nvidia-smi — Kit leaks if stages aren't properly cleared
  • GB10 (Jetson): Max ~35K prims, 16GB shared memory — reduce scene complexity

Known Issues (Kit 110)

  • DISPLAY=:0 required for headless viewport on Kit 110 with complex stages on some GPU configurations
  • Viewport never initializes without DISPLAY on some configurations — use --no-window + offscreen rendering
  • CUDA OOM: Monitor with nvidia-smi, keep under 90% GPU VRAM utilization
  • Startup time: ~30-60s cold start; use persistent processes for interactive batch
  • Newton physics + torch conflict: Never import torch before physics settle