Skip to content

docs(isaac): document a single Isaac Sim 6.0 install path (closes #108)#109

Open
yinsong1986 wants to merge 2 commits into
strands-labs:mainfrom
yinsong1986:docs/isaac-install-option-a
Open

docs(isaac): document a single Isaac Sim 6.0 install path (closes #108)#109
yinsong1986 wants to merge 2 commits into
strands-labs:mainfrom
yinsong1986:docs/isaac-install-option-a

Conversation

@yinsong1986

@yinsong1986 yinsong1986 commented Jun 18, 2026

Copy link
Copy Markdown
Contributor

What changed

Picks one supported Isaac Sim 6.0 install path and makes every surface agree on it, resolving the contradiction reported in #108.

The repo's prose (README, docs/index.md, docs/getting-started/installation.md, docs/troubleshooting.md, docs/backends/isaac.md, and strands_robots_sim/isaac/_install.py) all stated Isaac Sim is not on PyPI and must be installed out-of-band — but the [isaac] extra pinned isaacsim>=6.0 (and isaaclab>=3.0,<4.0), i.e. a PyPI install path the prose says isn't supported. Following that pin also produced a broken environment: NVIDIA's isaacsim[all] metapackage pulls the isaacsim-* packages but not the isaacsim-extscache-* packages, so SimulationApp aborts at boot with:

[Error] [omni.ext.plugin] Failed to resolve extension dependencies. ...
[Error] SimulationApp._start_app: Application failed to start.

and create_world() never starts.

This PR commits to Option A (the issue's recommended path): Isaac Sim is provisioned out-of-band via the Omniverse Launcher / Isaac Lab / NGC Docker image (each ships a complete, bootable Kit), and the pip extra carries only the genuinely pip-installable helper.

Diff (4 files, +117 / −45)

  • pyproject.toml — drop isaacsim>=6.0 and isaaclab>=3.0,<4.0 from the [isaac] extra; keep usd-core only. Comment block rewritten to explain the two reasons (internal consistency + the incomplete-metapackage boot failure).
  • docs/getting-started/installation.md — fix Step 2 prose (the [isaac] extra does not install Isaac Sim; it installs usd-core + strands-robots), and add a "Step 3 — verify your install boots" end-to-end snippet (create_world → add_robot → add_object → add_camera → step → render → destroy) that surfaces the extension-resolution failure if the install is incomplete.
  • docs/index.md — clarify the [isaac] extra installs only usd-core + strands-robots, not Isaac Sim.
  • strands_robots_sim/isaac/tests/test_entrypoint.py — replace the assertion that the extra pins isaacsim/isaaclab with test_isaac_extra_pins_only_pip_installable_helpers, which asserts the extra pins only usd-core and must not pin isaacsim/isaaclab (drift guard so the contradiction can't return).

Why

Following the documented install yielded a non-bootable environment, and the docs disagreed with packaging about how Isaac Sim is meant to be installed. Option A is the lower-friction, already-mostly-documented path: the Launcher/Docker/Isaac Lab images bundle a complete Kit (interpreter + full isaacsim-extscache-* extension set), so the pip extra only needs usd-core.

Test surface

  • hatch run lint — passes (black / isort / flake8, 51 files).
  • hatch run test203 passed, 33 skipped (skips are GPU/install-gated). Includes the updated test_entrypoint.py (16 passed).
  • No GPU on this contribution box, so the live SimulationApp boot in the new Step 3 snippet was authored from the reporter's verified sequence (create_world → … → render yielding a real (480, 640, 3) RGB + depth), not re-run here.

Acceptance criteria (#108)

  • Docs describe exactly one supported Isaac Sim 6.0 install path, with no "not on PyPI" vs isaacsim>=6.0-pin contradiction. (Option A; extra no longer pins isaacsim/isaaclab.)
  • Following that path yields a SimulationApp that boots and runs the quickstart. (Out-of-band Kit is complete; new Step 3 snippet verifies the boot, and Troubleshooting covers the incomplete-install failure.)

Also closes #107 (isaaclab pre-release trap)

This PR also resolves #107. The same pyproject.toml edit that drops isaacsim from [isaac] also drops isaaclab>=3.0,<4.0 — which #107 reports as independently uninstallable: the only isaaclab on the index is the pre-release 3.0.0b2, and PEP 440 excludes pre-releases from a >=3.0,<4.0 pin by default, so the whole [isaac] extra was unsatisfiable:

ERROR: Could not find a version that satisfies the requirement isaaclab<4.0,>=3.0; extra == "isaac" (from versions: 3.0.0b2)

A follow-up commit on this branch records the #107-specific root cause so it can't drift back in:

Acceptance criteria (#107)

  • pip install 'strands-robots-sim[isaac]' resolves cleanly on Python 3.12. (Extra now pins only usd-core; no isaaclab pre-release pin.)
  • The docs/index.md quickstart runs with exactly what [isaac] installs. (Core SimEngine surface needs only Isaac Sim — validated by the reporter on Isaac Sim 6.0 / Python 3.12 with only isaacsim, no isaaclab; Isaac Lab is the fleet-RL path, installed out-of-band from source.)

Out of scope (follow-ups, not this PR)

  • The environment note about Multiple Installable Client Drivers (ICDs) / CUDA error 101 under --/renderer/multiGpu/enabled=True, and exposing GPU/device selection via IsaacConfig. That's a runtime/config change unrelated to the install-path contradiction and deserves its own issue.

Project board

This issue is on the Strands Labs - Robots board; please move #108 and #107 to In review.

…ands-labs#108)

The repo's Isaac Sim 6.0 install guidance was internally contradictory:
the prose (README, docs/index.md, docs/getting-started/installation.md,
docs/troubleshooting.md, docs/backends/isaac.md, _install.py) all said
Isaac Sim is "not on PyPI / installed separately", but the `[isaac]`
extra pinned `isaacsim>=6.0` (and `isaaclab>=3.0,<4.0`) — a PyPI path the
prose says isn't supported. Worse, the PyPI `isaacsim[all]` metapackage
is incomplete on its own (it omits the `isaacsim-extscache-*` packages),
so `SimulationApp` aborts at boot with an `omni.ext` "Failed to resolve
extension dependencies" error and `create_world()` never starts.

This commits the repo to Option A (strands-labs#108): Isaac Sim installed out-of-band
via the Omniverse Launcher / Isaac Lab / NGC Docker image (each ships a
complete, bootable Kit), with the pip extra carrying only the genuinely
pip-installable helper.

Changes:
- pyproject.toml: drop `isaacsim`/`isaaclab` from the `[isaac]` extra;
  keep `usd-core` only. Rewrite the comment block to explain why.
- docs/getting-started/installation.md: fix Step 2 prose (the extra does
  not install Isaac Sim) and add a "Step 3 — verify your install boots"
  end-to-end snippet (create_world -> add_robot/object/camera -> step ->
  render -> destroy) that surfaces the extension-resolution failure.
- docs/index.md: clarify the `[isaac]` extra installs only `usd-core` +
  strands-robots, not Isaac Sim.
- test_entrypoint.py: replace the assertion that the extra pins
  `isaacsim`/`isaaclab` with one asserting it pins only `usd-core` and
  must NOT pin `isaacsim`/`isaaclab` (drift guard for the contradiction).

Out of scope (separate follow-ups): the GPU/ICD multi-GPU device-
selection note in the issue's environment section.
@yinsong1986 yinsong1986 requested a review from cagataycali June 18, 2026 10:19
…trands-labs#107)

The `[isaac]` extra previously pinned `isaaclab>=3.0,<4.0`, but the only
`isaaclab` distribution on the index is the pre-release `3.0.0b2`. Per
PEP 440, `>=3.0,<4.0` excludes pre-releases by default, so pip found no
eligible version and the *entire* `[isaac]` extra (and the documented
`pip install 'strands-robots-sim[isaac]'`) was unsatisfiable:

    ERROR: Could not find a version that satisfies the requirement
           isaaclab<4.0,>=3.0; extra == "isaac" (from versions: 3.0.0b2)

This change is on the same branch that already drops `isaaclab` (and
`isaacsim`) from `[isaac]` for strands-labs#108. It records the strands-labs#107-specific
root cause so the regression can't drift back in:

- pyproject.toml: extend the `[isaac]` comment to explain the
  pre-release/PEP-440 trap and that the fleet-RL path installs Isaac Lab
  from source (`./isaaclab.sh -i`), per docs/getting-started/installation.md.
- test_entrypoint.py: extend the `isaaclab not in [isaac]` drift-guard
  assertion message to cite strands-labs#107 and the pre-release reason.

Acceptance criteria (strands-labs#107):
- `pip install 'strands-robots-sim[isaac]'` resolves on Python 3.12
  (extra now pins only `usd-core`; no `isaaclab` pre-release pin).
- The docs/index.md quickstart runs with exactly what `[isaac]` installs
  (core SimEngine surface needs only Isaac Sim; Isaac Lab is fleet-RL only,
  installed out-of-band from source).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[isaac] extra is uninstallable: isaaclab>=3.0,<4.0 only has pre-release 3.0.0b2 on the index

1 participant