Isaac Sim Migration

Purpose

Move a project from one Isaac Sim release to another: inventory the affected surfaces with the release audit tool, triage findings into owned work, and prove each workflow still behaves correctly in the target release. This skill currently covers Isaac Sim 5.1 -> 6.0; for projects that skip releases, see "Migrating Across Releases" below.

Prerequisites

• An Isaac Sim source checkout that provides source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py, or a copy of that script placed in the project.
• Python 3 on PATH. The audit tool uses only the standard library.
• $WORKSPACE_DIR pointing at the project being migrated.
• A built or installed target-release Isaac Sim for the runtime validation step.

Limitations

• Covers Isaac Sim 5.1 -> 6.0 only; other hops need that release's own audit tool.
• The audit is a static inventory helper, not a complete analyzer. It can miss project wrappers, generated files, binary USD layers, dynamic imports, custom OmniGraph nodes, extension settings, and behavior that appears only at runtime.
• A clean report is not proof that the project is migrated.
• The installed Isaac Sim 6.0 package does not bundle tools/isaac_sim_migration/.

Troubleshooting

Error / symptom	Cause	Solution
audit_isaac_sim_6_0.py not found	Running against an installed package instead of a source checkout	Copy the script from the Isaac Sim repository into the project and run it with any Python 3
Audit reports nothing but the app still breaks	Static scan cannot see dynamic imports, generated files, or binary USD layers	Fall back to runtime validation per workflow; do not treat a clean report as done
CI fails on review findings	--fail-on set too broadly for the project	Gate on --fail-on required and triage review findings manually
Imports resolve but behavior changed	Migration changed timing, authored USD schemas, graph data flow, or output metadata	Run the empirical smoke test for that workflow instead of relying on import success
Deprecated extension imports cleanly	Deprecation is logged as a warning, not an error	Treat the warning as a migration finding and move to the replacement extension

Instructions

1. Scope first

Before editing code, identify:

• Source and target Isaac Sim versions.
• Install type: source checkout, binary package, container, or pip packages.
• Customer-owned surfaces: app .kit files, extension dependencies, Python, USD/USDA stages, Action Graphs, ROS 2 workspaces, robot assets, sensor configs, benchmark scripts, CI jobs, and generated data pipelines.
• Runtime smoke tests that prove the workflow still behaves correctly.

For Isaac Sim 5.1 -> 6.0, start with the 6.0 migration guide and the project audit tool in source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py.

2. Run the static audit

Run the audit tool from an Isaac Sim source checkout:

python source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py "$WORKSPACE_DIR" --max-results 0

For automation, use JSON output. The default exit code is success so teams can collect migration inventory without breaking CI:

python source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py "$WORKSPACE_DIR" --json --max-results 0

Gate only when the project explicitly wants unresolved findings to fail CI:

python source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py "$WORKSPACE_DIR" --fail-on required

Do not gate on review findings without project-specific triage rules.

3. Triage findings

Treat each finding as an owner assignment:

• required: likely breaking or removed behavior; assign a workflow owner and validate before closing.
• review: migration inventory; inspect manually and validate if the code path is active in the project.

Do not clear a finding because imports resolve. Isaac Sim migrations often change timing, authored USD schemas, graph data flow, package layout, and output metadata without producing immediate import errors. A deprecated extension may also import successfully while logging a deprecation warning; treat those warnings as migration findings and move the workflow to the replacement extension.

4. Validate at runtime

For each affected workflow, run an empirical smoke test in the target Isaac Sim release:

• Extension/app: start with the migrated dependency set and open one stage.
• Simulation: reset, step, and verify expected prim/articulation state.
• Sensors: create or load the sensor, step frames, and inspect cadence and output fields.
• Action Graphs: open the USD, let deprecation-manager graph migration run, save a migrated layer, then reopen it.
• ROS 2: launch, publish/subscribe one message path, and verify frame IDs, message fields, QoS-sensitive behavior, and package names.
• Robot assets: verify catalog path, validation status, articulation load, mimic joints, and importer/exporter round trip where relevant.
• Benchmarks: run one warmup and one measured phase; compare KPI names and recorder output shape against the old baseline.

Record evidence: target Isaac Sim version, command, app experience, input asset or workspace, expected 5.x behavior, observed 6.0 behavior, pass/fail result, and owner for remaining gaps.

Examples

Audit a customer workspace and read the full inventory:

export WORKSPACE_DIR=/path/to/customer_project
python source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py "$WORKSPACE_DIR" --max-results 0

Collect the same inventory as JSON for a migration tracking ticket, without failing the job:

python source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py "$WORKSPACE_DIR" \
  --json --max-results 0 > migration-audit.json

Gate a CI job on unresolved breaking findings only:

python source/tools/isaac_sim_migration/audit_isaac_sim_6_0.py "$WORKSPACE_DIR" --fail-on required

Validate one triaged ROS 2 finding in the target release before closing it:

"$ISAAC_SIM_DIR/python.sh" -c "import isaacsim; print(isaacsim.__file__)"
# then launch the project's ROS 2 graph and verify one publish/subscribe path,
# frame IDs, and package names against the 5.x baseline

Deprecation Warnings

Use deprecation warnings as a signal, not as the only migration mechanism. isaacsim.core.deprecation_manager currently migrates deprecated settings and saved OmniGraph node namespaces, and logs what it changes. It is not a general system that guarantees every deprecated Python symbol warns on import or use.

Migrating Across Releases

Each release migration has its own audit tool and guides; this skill currently covers Isaac Sim 5.1 -> 6.0 via audit_isaac_sim_6_0.py. When a project skips releases, run each release-to-release migration in order (for example 5.1 -> 6.0, then 6.0 -> 6.1), using that release's audit tool and guides, and validate the project at each hop before starting the next one.