feat: make IsaacLab pip/uv installable via workspace meta-package

[lgulich]

Problem

Today, there's no way to pip install or uv sync IsaacLab from a downstream project. Installation requires cloning the repo and running isaaclab.sh --install, which:

• Installs ~12 sub-packages one by one in the right order
• Manually installs isaacsim with the correct index URL
• Sets up Kit extension paths via filesystem conventions

This makes it impossible to declare IsaacLab as a dependency in a downstream pyproject.toml and have everything "just work."

Solution

Add modern Python packaging (pyproject.toml with PEP 621 [project] sections) to 4 core sub-packages and create a root isaac-lab meta-package with a uv workspace. A downstream project can now install everything with:

dependencies = ["isaac-lab"]

[tool.uv.sources]
isaac-lab = { git = "https://github.com/isaac-sim/IsaacLab.git", branch = "main" }

[tool.uv]
extra-index-url = ["https://pypi.nvidia.com", "https://download.pytorch.org/whl/cu128"]
index-strategy = "unsafe-best-match"

Or with a requirements.txt:

--extra-index-url https://pypi.nvidia.com
--extra-index-url https://download.pytorch.org/whl/cu128
isaaclab @ git+https://github.com/isaac-sim/IsaacLab.git@main#subdirectory=source/isaaclab
isaaclab-assets @ git+https://github.com/isaac-sim/IsaacLab.git@main#subdirectory=source/isaaclab_assets
isaaclab-tasks @ git+https://github.com/isaac-sim/IsaacLab.git@main#subdirectory=source/isaaclab_tasks
isaaclab-rl @ git+https://github.com/isaac-sim/IsaacLab.git@main#subdirectory=source/isaaclab_rl

Changes

• Move package metadata from setup.py to pyproject.toml [project] sections for isaaclab, isaaclab-assets, isaaclab-tasks, isaaclab-rl
• Add inter-package dependencies (e.g. isaaclab-tasks depends on isaaclab and isaaclab-assets)
• Add isaacsim[all,extscache]==5.1.0 as a dependency of isaaclab
• Add root isaac-lab meta-package with [tool.uv.workspace] configuration
• Add extra-index-url for pypi.nvidia.com and PyTorch CUDA wheels
• Set index-strategy = "unsafe-best-match" for cross-index resolution
• Bundle .kit experience files inside the isaaclab package with fallback path resolution in AppLauncher and SimulationContext (so the sim boots without the repo layout)
• Make extension.toml loading optional in __init__.py (fall back to importlib.metadata for non-editable installs)
• Keep setup.py as backward-compatible shims so isaaclab.sh --install still works

Test plan

• uv lock resolves 245 packages successfully
• uv sync installs all packages into a fresh venv from a downstream project
• All 6 packages report correct versions via importlib.metadata.version()
• import isaaclab and import isaaclab_rl work in non-editable install
• Isaac Sim boots, creates SimulationContext, steps physics (headless, GPU)
• requirements.txt approach also installs and runs correctly
• Verify isaaclab.sh --install still works with the shim setup.py files

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR migrates all package metadata from setup.py to pyproject.toml for all four Isaac Lab sub-packages and adds a root isaac-lab meta-package with uv workspace configuration, enabling uv sync to install the full framework including Isaac Sim.

• The root meta-package correctly restricts requires-python = ">=3.11,<3.12" (Isaac Sim 5.1.0 requires Python 3.11), but this upper bound is absent from source/isaaclab/pyproject.toml; a direct pip install isaaclab on Python 3.12 will appear to succeed but fail at Isaac Sim runtime.

Confidence Score: 4/5

Mostly safe to merge; one P1 concern about the missing Python upper-bound on the isaaclab sub-package.

Score of 4 reflects one P1 finding: the <3.12 upper bound is enforced at the meta-package level but not propagated to source/isaaclab/pyproject.toml, risking silent failures on unsupported Python versions. All other findings are P2 style/maintenance suggestions.

source/isaaclab/pyproject.toml needs <3.12 added to requires-python; source/isaaclab_rl/pyproject.toml all extra needs documentation or automation to prevent drift.

Important Files Changed

Filename	Overview
pyproject.toml	New root isaac-lab meta-package with uv workspace config; requires-python upper bound not propagated to sub-packages
source/isaaclab/pyproject.toml	Dependencies migrated from setup.py; starlette dropped, flatdict unpinned, requires-python lacks <3.12 upper bound
source/isaaclab/setup.py	Reduced to backward-compatible shim calling setup()
source/isaaclab_assets/pyproject.toml	Clean minimal declaration depending only on isaaclab
source/isaaclab_assets/setup.py	Backward-compatible shim
source/isaaclab_rl/pyproject.toml	Extras correctly declared but all extra is manually maintained and may drift
source/isaaclab_rl/setup.py	Backward-compatible shim
source/isaaclab_tasks/pyproject.toml	Clean dependency declaration with proper inter-package deps
source/isaaclab_tasks/setup.py	Backward-compatible shim

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  META["isaac-lab\nmeta-package v2.3.2"]
  IL["isaaclab v0.54.3"]
  IA["isaaclab-assets v0.2.4"]
  IT["isaaclab-tasks v0.11.14"]
  IRL["isaaclab-rl v0.5.0"]
  ISIM["isaacsim\nall,extscache==5.1.0"]
  META --> IL
  META --> IA
  META --> IT
  META --> IRL
  IL --> ISIM
  IA --> IL
  IT --> IL
  IT --> IA
  IRL --> IL
  IRL --> IA
  IRL --> IT

Loading

_{Reviews (1): Last reviewed commit: "feat: make IsaacLab pip/uv installable v..." | Re-trigger Greptile}

[greptile-apps]

starlette dependency dropped

The old setup.py listed "starlette==0.49.1" with a # livestream comment; it is absent from the new pyproject.toml. starlette is not directly imported in the current isaaclab source, so the removal may be intentional — please confirm it was a deliberate omission and not an oversight during the migration.

[lgulich]

Deliberate removal. starlette==0.49.1 conflicts with isaacsim's fastapi dependency which requires starlette>=0.40.0,<0.46.0. Starlette is provided transitively by isaacsim via fastapi, so the explicit pin is not needed.

[kellyguo11]

@myurasov-nv for viz

[isaaclab-review-bot]

Review: pip/uv installable meta-package

This is a well-motivated and well-structured PR. Making IsaacLab pip install-able from downstream projects is a significant ergonomic improvement. The approach — PEP 621 [project] sections, uv workspace, backward-compatible setup.py shims, bundled .kit files with fallback path resolution — is sound.

Below are observations organized by severity.

---

🔴 Issues

1. starlette dependency dropped silently
The old source/isaaclab/setup.py had starlette==0.49.1 (for livestream). The new pyproject.toml doesn't include it. If any user code or IsaacLab code imports starlette for livestreaming, this will be a runtime ImportError on fresh pip/uv installs. Was this intentional? If livestream is now handled by an isaacsim extension, it's fine — but worth noting in the PR description.

2. isaaclab_rl/__init__.py not updated with extension.toml fallback
The __init__.py files for isaaclab, isaaclab_assets, and isaaclab_tasks all get the conditional extension.toml → importlib.metadata fallback. But isaaclab_rl/__init__.py is not modified. Checking the current code: it doesn't load extension.toml at the top, so this is fine — just verifying it doesn't break. 👍

3. isaaclab_mimic and isaaclab_contrib not included in workspace
The uv workspace only has 4 members. The repo has 6 sub-packages (isaaclab_contrib, isaaclab_mimic). If someone does uv sync from root and then tries to import isaaclab_mimic, it won't be installed. Is this intentional scope reduction, or a follow-up? Should be documented.

4. Version pinning drift risk
Versions are now hardcoded in 5 separate pyproject.toml files (root isaac-lab 2.3.2, isaaclab 0.54.3, isaaclab-assets 0.2.4, isaaclab-tasks 0.11.14, isaaclab-rl 0.5.0) AND still in extension.toml for editable installs. There's no single source of truth anymore. The __init__.py fallback logic picks one or the other based on install mode, but they could diverge. Consider either:

• Reading version from extension.toml at build time (dynamic version)
• Or having the pyproject.toml be authoritative and deprecating the extension.toml version field

---

🟡 Suggestions

5. requires-python narrowed to >=3.11,<3.12
The old setup.py had python_requires=">=3.10". The new pyproject.toml says >=3.11,<3.12. This is fine for Isaac Sim 5.1 (which requires 3.11), but it's a breaking change for anyone on 3.10. Worth calling out in the PR description. Also — the root pyproject.toml and sub-packages all have >=3.11,<3.12, which is consistent. 👍

6. unsafe-best-match index strategy
This is documented in the PR body but worth noting: index-strategy = "unsafe-best-match" in [tool.uv] means uv will pick the best-matching version across ALL configured indexes, which can lead to dependency confusion attacks if a malicious package with a higher version is published to PyPI with the same name as an internal NVIDIA package. For a framework like IsaacLab this is likely acceptable (the NVIDIA packages are all on pypi.nvidia.com), but downstream users should understand the security implications.

7. Bundled .kit files are large (~1000 lines)
The 6 bundled .kit files add ~1000+ lines to the package. These appear to be copies of the existing apps/ directory .kit files, bundled inside the Python package for non-editable installs. This works but creates a maintenance burden — any .kit change needs to be mirrored. Consider symlinking or generating these from a single source, or at minimum adding a comment noting they're copies.

8. rendering_modes/extension.toml is a dummy file
The file at source/isaaclab/isaaclab/apps/rendering_modes/extension.toml contains only # This is not an extension. If this is needed to prevent Kit from treating the directory as an extension, add a brief explanation comment. Otherwise it looks like an accidental inclusion.

9. [tool.setuptools.packages.find] in isaaclab pyproject.toml
The config uses include = ["isaaclab*"] which will match isaaclab and all sub-packages. This is correct, but in a workspace where isaaclab_assets, isaaclab_tasks, etc. are siblings, make sure the find doesn't accidentally pull in adjacent packages. Since where = ["."] is relative to source/isaaclab/, it should be scoped correctly.

---

✅ What looks good

• Clean separation: pyproject.toml for metadata, setup.py as shim for backward compat
• Proper inter-package dependencies (isaaclab-tasks → isaaclab + isaaclab-assets)
• isaacsim[all,extscache]==5.1.0 as a first-class dependency — this is the key enabler
• Fallback path resolution in AppLauncher and SimulationContext is minimal and correct
• extension.toml → importlib.metadata fallback is well-implemented
• extra-index-url for NVIDIA and PyTorch CUDA wheels
• Optional dependencies in isaaclab-rl (sb3, skrl, rl-games, rsl-rl) are well-organized
• Test plan is solid (though isaaclab.sh --install is unchecked — please verify before merge)

Overall: strong direction. Address the starlette question, document the scope (4/6 packages), and verify the isaaclab.sh --install shim path, and this is good to go.

[isaaclab-review-bot]

isaacsim[all,extscache]==5.1.0 — this is the key enabler for pip-installability. Pinning to exact version is the right call since Kit extensions are not semver-compatible across Isaac Sim versions.

One concern: when Isaac Sim 5.2 ships, every downstream project pinned to isaac-lab will need to wait for a new release. Consider whether a >=5.1.0,<5.2 range would be more practical, or if exact pin is intentional.

[isaaclab-review-bot]

The old setup.py included starlette==0.49.1 for livestream support. This dependency is absent here. Was this intentional? If livestream functionality depends on starlette being installed, this will break for pip/uv users.

[isaaclab-review-bot]

Clean fallback pattern. One thought: if this is a non-editable install, ISAACLAB_METADATA will only have version and description keys under package, while editable installs get the full extension.toml dict (repository, keywords, authors, etc.). Any downstream code that accesses other fields of ISAACLAB_METADATA["package"] will get a KeyError in non-editable mode.

Consider either:

• Documenting which keys are guaranteed
• Populating more fields from importlib.metadata in the fallback

[isaaclab-review-bot]

Suggested change

	index-strategy = "unsafe-best-match"
	[tool.uv.extra-build-dependencies]
	flatdict = ["setuptools"]

What's the story here? flatdict needs setuptools as a build dep? Is this a known upstream issue with flatdict's build, or a workaround for something specific? A brief comment would help future maintainers.

[isaaclab-review-bot]

This fallback path (.. instead of ../../../..) for bundled apps is correct. The directory structure for editable is source/isaaclab/isaaclab/app/ → 4 levels up to apps/, while for installed it's site-packages/isaaclab/app/ → 1 level up to isaaclab/apps/.

Nit: the same pattern is duplicated in simulation_context.py. Consider extracting a helper function like get_isaaclab_apps_path() to avoid the duplication.