Skip to content

Update the central pyproject, remove subpackage specific dependencies#6009

Open
StafaH wants to merge 12 commits into
isaac-sim:developfrom
StafaH:mh/pyproject_cleanup
Open

Update the central pyproject, remove subpackage specific dependencies#6009
StafaH wants to merge 12 commits into
isaac-sim:developfrom
StafaH:mh/pyproject_cleanup

Conversation

@StafaH

@StafaH StafaH commented Jun 6, 2026

Copy link
Copy Markdown
Contributor

Description

Consolidates all dependencies into the central pyproject. This should make it easier to maintain a ground truth.

Checklist

  • I have read and understood the contribution guidelines
  • I have run the pre-commit checks with ./isaaclab.sh --format
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • I have updated the changelog and the corresponding version in the extension's config/extension.toml file
  • I have added my name to the CONTRIBUTORS.md or my name already exists there

@github-actions github-actions Bot added documentation Improvements or additions to documentation isaac-mimic Related to Isaac Mimic team infrastructure labels Jun 6, 2026

@isaaclab-review-bot isaaclab-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review Summary

This PR centralizes all Isaac Lab third-party dependency declarations into the root pyproject.toml, removing per-subpackage dependency specifications. The approach establishes a single source of truth that the wheel builder, ./isaaclab.sh -i CLI, and uv workspace all consume. The architectural direction is sound and will significantly reduce maintenance burden for version bumps across the monorepo.


🔴 Critical: Wheel Extras Resolution Failure (CI Blocked)

The Build Wheel CI check fails because isaaclab[isaacsim,all] cannot co-resolve:

isaacsim-core==6.0.0.0 depends on imgui-bundle==1.92.4
isaaclab[all] depends on imgui-bundle>=1.92.5

isaacsim-kernel==6.0.0.1 depends on typing-extensions==4.12.2
isaaclab[all] depends on typing-extensions>=4.15.0

The newton extra (which feeds into all) raises imgui-bundle>=1.92.5 and typing-extensions>=4.15.0, but Isaac Sim pins these lower. In the old structure this was avoided because the newton viewer deps were only installed via isaaclab_visualizers[newton] which was not part of the wheel's all extra when isaacsim was also active.

Suggested fix: Either (a) move imgui-bundle and typing-extensions out of the all aggregate (like viser is excluded in the old python_packages.toml), or (b) relax the lower bounds to accommodate Isaac Sim's pins (e.g., imgui-bundle>=1.92.4), or (c) declare an explicit conflicts for [isaacsim] vs [newton] in the wheel metadata.


🟡 Medium: OPTIONAL_SUBMODULE_ROOT_EXTRAS Declares mimic("mimic", "teleop") Despite Conflict

In install.py, the mapping:

OPTIONAL_SUBMODULE_ROOT_EXTRAS: dict[str, tuple[str, ...]] = {
    "mimic": ("mimic", "teleop"),
    "teleop": ("teleop",),
}

But the root pyproject.toml declares:

conflicts = [
    [{ extra = "teleop" }, { extra = "mimic" }],
    ...
]

These two extras cannot co-resolve (lxml version conflict). The _install_centralized_dependencies path will attempt to pip install both the mimic and teleop extras' requirements sequentially — pip doesn't enforce uv-style conflict declarations, so this may silently install incompatible lxml versions. Consider either:

  • Removing "teleop" from mimic's root extras mapping, or
  • Adding a runtime warning/skip when both are requested, matching the conflict declaration's intent.

🟡 Medium: packaging Version Pin Relaxed

The isaaclab_rl package previously pinned packaging<24 (required by certain moviepy versions). The root pyproject.toml now lists "packaging" without an upper bound. If downstream users have moviepy versions that rely on packaging<24 behavior, this could cause subtle runtime issues with video recording utilities.


🟢 Minor: all Extra Duplicates Individual Extras Inline

The all extra lists every dependency inline rather than referencing the other extras. This means version bumps must be synchronized in two places (the individual extra AND all). Consider whether the wheel builder or uv supports extra self-references (e.g., {include-group = "sb3"}) to keep them DRY, or add a test that verifies all is a superset of the union of the named extras.


🟢 Minor: Documentation Hardcodes Dependency Lists

The docs (e.g., bleeding-edge.rst, rlinf_vla_posttraining.rst) now inline the full pip install command with specific versions:

pip install "ray[default]>=2.47.0" "av>=12.3.0" ...

These will drift from the root pyproject.toml over time. Consider referencing the extra instead (e.g., pip install isaaclab[rlinf] for wheel users, or uv run --extra rlinf for source users) to maintain the single-source-of-truth principle this PR establishes.


🟢 Positive Observations

  • The [tool.isaaclab.wheel-extras] pattern for isaacsim is a clean solution for keeping conflicting extras out of workspace resolution while still shipping them in the wheel.
  • The constraint-dependencies for the torch stack (pinning exact versions for dev while keeping wheel specs loose) is well-designed.
  • The conflict declarations for teleop/mimic/all are appropriate given the lxml incompatibility.
  • Test coverage updates are thorough — the new test_wheel_builder_metadata.py integration test that actually runs gen_pyproject.py is a strong improvement over the old static TOML checks.
  • Changelog entries and .skip markers are correctly structured.

Update (429f245): The 55 new commits since my previous review introduce extensive changes unrelated to the core dependency centralization:

  • Task restructuring: Cabinet, reorient/handover/pendulum consolidation, lift refactoring, env ID renames (dropping -v0 suffixes)
  • Physics backend migration: Newton presets for stack/place tasks, backend-decoupled cloning API (clone_environmentsClonePlan/replicate)
  • Infrastructure: AutoMate Numba→Torch SoftDTW replacement, ISP optional-dependency guard, LEAPP export fixes

Previous concerns status:

  • 🔴 Wheel extras resolution (imgui-bundle/typing-extensions conflict): Not addressed — still applicable
  • 🟡 mimic→teleop conflict mapping: Not addressed
  • 🟡 packaging pin relaxation: Not addressed
  • 🟢 all extra duplication / docs hardcoding: Not addressed

New issues in this diff: None found. The refactoring is internally consistent — renamed env IDs, restructured packages, and new validate_config() guards are well-implemented. The SoftDTW rewrite correctly preserves autograd support. The cloner migration is uniform across all direct envs.


Update (23dd23c): The latest push addresses several previous concerns:

  • Wheel extras resolution (imgui-bundle/typing-extensions): Fixed. typing-extensions lowered to >=4.12.2 to match isaacsim's pin. The all extra now explicitly excludes newton, ov, viser, and mimic's USD-to-URDF converter — packages whose pins conflict with isaacsim — with clear documentation directing users to install them separately.
  • all extra duplication: Fixed. all now uses self-referential extras (isaaclab-dev[sb3,skrl,rl-games,rsl-rl,newton,rerun,rlinf]) instead of inlining every dependency. The wheel builder gains _expand_self_refs() to resolve these during generation — clean and DRY.
  • Newton pinning strategy: Good approach — loose newton[sim]>=1.2.0 in [project.dependencies] for the published wheel (co-resolves with isaacsim's pin), while [tool.uv.sources] tracks the git prerelease for the dev workspace.
  • 🟡 packaging upper-bound removal: Not addressed (original inline comment stands).
  • 🟡 mimic→teleop conflict mapping in install.py: Not addressed.

New changes look good: Removal of the rl-all aggregate extra (replaced by iterating individual framework extras in install.py), the isaacsim==6.0.0.1 exact pin, and license exception additions are all clean. No new issues found.

@isaaclab-review-bot isaaclab-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 Code Review: Dependency Centralization

Thanks for this significant refactoring effort to consolidate dependencies into the root pyproject.toml. This is a valuable architectural improvement that will make dependency management much easier to maintain. Here's my analysis:

Strengths

  1. Single Source of Truth: Moving all dependencies to the root pyproject.toml eliminates the scattered dependency declarations across ~15 sub-packages, making it much easier to audit and update versions.

  2. Well-Documented Changes: The changelog entries clearly explain the behavioral change (Newton is now a core dependency) and the architectural shift.

  3. Comprehensive Test Updates: The tests have been properly updated to reflect the new structure, particularly in test_uv_run_pyproject.py and test_wheel_builder_metadata.py.

  4. Conflict Resolution: Good use of [tool.uv] conflicts to handle the teleop/mimic lxml version conflict gracefully.

  5. Wheel Builder Simplification: Removing res/python_packages.toml and having gen_pyproject.py read directly from the root pyproject reduces duplication and potential for drift.


⚠️ Concerns & Suggestions

1. Pinning Strategy Inconsistency

The root pyproject mixes loose (>=) and exact (==) version specifiers without clear rationale:

"torch>=2.10",              # loose
"pillow==12.1.1",           # exact
"transformers==4.57.6",     # exact
"matplotlib>=3.10.3",       # loose

Suggestion: Consider documenting why certain packages are pinned exactly (Isaac Sim compatibility?) vs. loosely. This helps future maintainers understand when they can update vs. when caution is needed.

2. [tool.uv.constraint-dependencies] Duplication Risk

[tool.uv]
constraint-dependencies = [
    "torch==2.10.0",
    "torchvision==0.25.0",
    "torchaudio==2.10.0",
]

While the comment explains the reasoning, there's now a disconnect: [project.dependencies] has torch>=2.10 but constraints pin ==2.10.0. If someone reads just the dependencies section, they might not realize the workspace resolution will differ from the published wheel resolution.

Suggestion: Add a comment in the [project.dependencies] section pointing to the constraint-dependencies section.

3. all Extra Expansion

The all extra now explicitly lists every dependency rather than referencing other extras:

all = [
    "stable-baselines3>=2.6",
    "tqdm",
    "rich",
    # ... many more
]

This creates maintenance burden – if you update sb3 extra, you must also update all. The previous approach of referencing extras was DRYer.

Suggestion: Consider whether all could reference other extras, or add a test that validates all is a superset of all other extras.

4. Install CLI Changes Need Integration Testing

The changes to install.py are substantial:

  • New _root_core_dependencies() and _root_extra_dependencies() functions
  • _install_centralized_dependencies() replacing per-package dependency resolution
  • Mapping changes (ov[ovrtx]rtx extra, etc.)

Question: Have these paths been tested with the actual ./isaaclab.sh -i command? Unit tests mock out the pip calls, so integration behavior could differ.

5. Documentation Updates May Be Incomplete

The docs changes show users should now run:

pip install "ray[default]>=2.47.0" "av>=12.3.0" ...

instead of the simpler:

uv pip install -e "source/isaaclab_contrib[rlinf]"

This is a UX regression for contrib users – they now need to know individual packages.

Question: Should there be a simpler command like ./isaaclab.sh -i rlinf to install these dependencies?

6. Missing h5py in Root Core Dependencies

isaaclab_mimic previously depended on h5py>=3.15.0 for data collection. I see h5py is now only in the RL utilities section, but is it still available for mimic workflows?


🔬 Minor Nits

  1. Line 88 in pyproject.toml: Comment says "RL utilities" but packaging is listed there – is packaging an RL utility?

  2. _TORCH_DISTRIBUTIONS set in install.py: Consider making this a frozenset for immutability.

  3. Changelog file naming: centralize-deps-root-pyproject.rst is quite long – consider shorter names for future changelogs.


📋 Checklist Observations

Based on the PR checklist:

  • Pre-commit checks: Not visible in the diff, please confirm ./isaaclab.sh --format passes
  • Tests: Unit tests updated ✅, but consider integration test coverage
  • Changelog: Present ✅
  • extension.toml version: Not applicable (this is pyproject.toml changes)

Summary

This is a well-executed refactoring with clear benefits for maintainability. The main suggestions are around documenting pinning rationale, ensuring the all extra stays in sync, and verifying integration test coverage for the install CLI changes.

Would appreciate clarification on the integration testing and the contrib/rlinf UX change before merging.

@greptile-apps

greptile-apps Bot commented Jun 6, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR consolidates all Isaac Lab third-party dependencies into the root pyproject.toml, making it the single source of truth for the uv workspace, the wheel builder (gen_pyproject.py), and the ./isaaclab.sh -i CLI. Sub-package pyproject.toml files now declare empty dependencies = [], and the old tools/wheel_builder/res/python_packages.toml is deleted.

  • Dependency centralization: All third-party runtime and optional deps (Newton, rsl-rl, RL frameworks, visualizer backends, mimic/teleop stacks, rlinf extras) are moved to the root pyproject.toml; version constraints in constraint-dependencies pin the exact torch stack for the dev workspace without constraining the published wheel.
  • CLI re-wiring: install.py gains _root_core_dependencies / _install_root_extra / _install_centralized_dependencies helpers that read the root pyproject and drive pip calls in place of the old per-subpackage editable installs with extras; extra-name mappings (rl[all]rl-all, ov[ovphysx]ov, etc.) are implemented inline with comments.
  • Wheel builder: gen_pyproject.py is rewritten to parse the root pyproject, strip isaaclab* workspace self-references, and merge [tool.isaaclab.wheel-extras] (which holds the isaacsim extra excluded from uv workspace resolution) into the generated wheel metadata.

Confidence Score: 4/5

The change is a large but mechanical reorganization: sub-packages lose their dep declarations and the root pyproject becomes the single authority. The logic is straightforward and well-tested; no runtime behavior changes outside the install CLI and wheel builder.

The rework is sound and the new helpers mirror the old editable-install approach closely. The main open question is the silent removal of the packaging<24 upper bound that isaaclab_rl previously enforced — if any code path relies on pre-v24 packaging APIs, this would fail at runtime rather than install time. The pip-vs-uv-pip inconsistency in the docs is minor but could trip up users following the rlinf setup guide.

The root pyproject.toml (specifically the packaging entry and the new all extra composition) and docs/source/experimental-features/bleeding-edge.rst (inconsistent pip vs uv pip install command) deserve a second look before merge.

Important Files Changed

Filename Overview
pyproject.toml Central consolidation of all third-party deps; introduces constraint-dependencies for torch pinning and uv conflict declarations; some version constraints differ from old python_packages.toml (packaging upper bound dropped, hidapi loosened).
source/isaaclab/isaaclab/cli/commands/install.py New helpers (_root_core_dependencies, _install_root_extra, _install_centralized_dependencies) read deps from root pyproject; existing _install_extra_feature and _install_ov_extra_dependencies are re-wired to those helpers with correct extra-name mappings.
tools/wheel_builder/gen_pyproject.py Rewritten to parse the root pyproject.toml instead of the custom python_packages.toml; strips workspace members via _is_workspace_member and merges [tool.isaaclab.wheel-extras] for the isaacsim wheel-only extra.
source/isaaclab/test/cli/test_wheel_builder_metadata.py Tests updated to exercise gen_pyproject.py against the real root pyproject; now validates workspace-member stripping, wheel-only isaacsim extra, and rsl-rl pin consistency.
docs/source/experimental-features/bleeding-edge.rst Updated install instructions to use plain pip install for rlinf deps, while the companion rlinf_vla_posttraining.rst uses uv pip install for the same command — inconsistent UX guidance.
source/isaaclab/test/cli/test_install_command_parsing.py New _root_core_dependencies and _install_root_extra helpers correctly added to the mock-patch list, preventing tests from hitting the filesystem or pip during unit runs.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["root pyproject.toml\n(single source of truth)"]

    subgraph DevWorkspace ["uv Dev Workspace"]
        A -->|"core deps + constraint-dependencies\n(torch pinned)"| B["uv lock / uv sync"]
        A -->|"optional-dependencies extras"| B
        A -->|"[tool.uv.sources] editable refs"| C["isaaclab* sub-packages\n(empty dependencies=[])"]
    end

    subgraph CLI ["./isaaclab.sh -i"]
        D["command_install()"] -->|"_install_centralized_dependencies()"| E["_root_core_dependencies()\nreads root pyproject, strips torch + isaaclab*"]
        D -->|"optional submodule extras"| F["_install_root_extra(extra)\nreads optional-dependencies[extra]"]
        D -->|"_install_extra_feature()"| F
    end

    subgraph WheelBuilder ["tools/wheel_builder"]
        G["build.sh"] -->|"gen_pyproject.py root/pyproject.toml"| H["gen_pyproject.py\nstrips isaaclab* workspace members\nmerges tool.isaaclab.wheel-extras"]
        H --> I["generated wheel pyproject.toml\n(isaacsim extra from wheel-extras)"]
    end

    A -->|"_load_root_pyproject()"| CLI
    A -->|"tomllib.load()"| WheelBuilder
Loading

Reviews (1): Last reviewed commit: "Move pyproject dependencies to root" | Re-trigger Greptile

Comment on lines +31 to +35
# The base contrib package is installed with the core Isaac Lab packages.
# Install its optional dependencies (e.g., for RLinf VLA post-training) with pip:
pip install "ray[default]>=2.47.0" "av>=12.3.0" "numpydantic>=1.7.0" \
"albumentations>=1.4.18" decord2 "dm_tree>=0.1.8" "diffusers>=0.35.0" \
"timm>=1.0.14" "peft>=0.17.0" pandas

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 The install command here uses bare pip install while the companion guide rlinf_vla_posttraining.rst uses uv pip install for the identical rlinf dependency list. In an Isaac Lab checkout where uv manages the environment, bare pip may resolve to the system Python rather than the active virtual environment, silently installing into the wrong interpreter. Both files should use the same tool.

Suggested change
# The base contrib package is installed with the core Isaac Lab packages.
# Install its optional dependencies (e.g., for RLinf VLA post-training) with pip:
pip install "ray[default]>=2.47.0" "av>=12.3.0" "numpydantic>=1.7.0" \
"albumentations>=1.4.18" decord2 "dm_tree>=0.1.8" "diffusers>=0.35.0" \
"timm>=1.0.14" "peft>=0.17.0" pandas
# The base contrib package is installed with the core Isaac Lab packages.
# Install its optional dependencies (e.g., for RLinf VLA post-training) with uv pip:
uv pip install "ray[default]>=2.47.0" "av>=12.3.0" "numpydantic>=1.7.0" \
"albumentations>=1.4.18" decord2 "dm_tree>=0.1.8" "diffusers>=0.35.0" \
"timm>=1.0.14" "peft>=0.17.0" pandas

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^

Comment thread pyproject.toml
"rl-games @ git+https://github.com/isaac-sim/rl_games.git@python3.11",
"gym",
"standard-distutils",
]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Silent removal of packaging<24 upper-bound

source/isaaclab_rl/pyproject.toml previously pinned packaging<24 — likely because packaging v24 dropped several deprecated APIs (e.g. LegacyVersion, parse_version returning a LegacyVersion for non-PEP-440 strings). The new root entry is simply "packaging" with no upper bound. If anything in isaaclab_rl or downstream code exercises those removed APIs, the install will succeed silently but fail at runtime. It is worth confirming no code path touches packaging.version.LegacyVersion or similar symbols before dropping this constraint.

@AntoineRichard

Copy link
Copy Markdown
Collaborator

Yes let's do this :D

Comment thread .github/workflows/license-check.yaml Outdated
uv sync --extra all
# Isaac Sim isn't in the dev pyproject; sync first so it isn't pruned.
uv pip install 'isaacsim[all,extscache]==${{ vars.ISAACSIM_BASE_VERSION || '6.0.0' }}'
uv pip install 'isaacsim[all,extscache]==${{ vars.ISAACSIM_BASE_VERSION || '6.0.0.1' }}'

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we have one common place where we define version of IsaacSim? I can see this going out of sync very quickly.

In the past, in OV projects what worked well is VERSION file. That file in the root of the repo had definitions of all most important dependencies.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a single source of truth for isaacsim version in the pyproject.toml

},
{
"package": "ovrtx",
"license": null,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to find out this information.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated

Comment thread docs/_extensions/isaaclab_docs.py Outdated
--extra-index-url https://pypi.nvidia.com \\
--index-strategy unsafe-best-match --prerelease=allow
uv pip install -U torch==2.10.0 torchvision==0.25.0 \\
uv pip install -U torch==2.11.0 torchvision==0.26.0 \\

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a way to also centralized this where possible? Or it's fine as we might not update it often?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Centralized

.. code-block:: bash

pip install --extra-index-url https://pypi.nvidia.com -e "source/isaaclab_ov[ovrtx]"
pip install --extra-index-url https://pypi.nvidia.com "ovrtx>=0.3.0,<0.4.0"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems to be another maintenance point, can we rely on one path?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Centralized


.. code-block:: bash

pip install -U torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

apply the same as sim version?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Centralized

Comment on lines +584 to +586
OPTIONAL_SUBMODULE_ROOT_EXTRAS: dict[str, tuple[str, ...]] = {
"mimic": ("mimic", "teleop"),
"teleop": ("teleop",),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't full understand install.py yet, but could this also live in pyproject?

@diegoferigo-rai diegoferigo-rai left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @StafaH for the contribution. I'm quite concerned about the direction this PR is taking, as it makes downstream consumption significantly more difficult.

In my view, the packages under src/ (which are the ones that could eventually be published independently to PyPI) should be self-contained. Each package should define all of its own metadata and dependencies in its pyproject.toml, so that it remains functional and installable outside the context of this repository.

I do like the idea of having a repository-wide lock file, but I would expect the dependency declarations at the top level to remain relatively slim and primarily aggregate the requirements of the packages in src/.

One potential benefit of the top-level pyproject.toml would be to centralize the stricter version constraints required for IsaacSim, while keeping the package-level dependency specifications in src/ more relaxed and suitable for standalone use.

Happy to discuss this further.

Comment on lines +19 to +22
# Third-party requirements are centralized in the root pyproject.toml
# (single source of truth for the uv workspace, the wheel builder, and the
# ./isaaclab.sh -i install CLI).
dependencies = []

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From a packaging perspective, I don't think this approach is viable.

I understand the need for an isaaclab-dev catch-all metapackage, but that should not influence the packaging semantics of the individual packages. Each package should remain valid as a standalone distribution, with a complete and accurate declaration of its own dependencies.

If stricter version pinning is needed for development or repository-wide compatibility, that can be enforced at the top-level isaaclab-dev package. The individual packages, however, should retain dependency specifications that reflect their actual requirements and support independent installation and distribution.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's a valid point. I think part of what we wanted to achieve here is that we can have a central location that guards the version pinning for our dependencies so that we don't end up with multiple packages specifying the same dependency, but could easily misalign in versioning because someone forgot to update it.

perhaps there's a better way to handle both of these needs. ideally we can have a central place that acts as the source of truth for all version pinning, and each package will hold its own list of dependencies and pull the versioning from the central location. maybe the per-package pyproject.toml files could be constructed from the central one?

@diegoferigo diegoferigo Jun 23, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the individual packages should remain self-contained and define a sufficiently relaxed set of dependencies so that their package metadata is complete and accurate. Moving dependency definitions elsewhere would result in incomplete metadata. For example, if isaaclab-newton is published on PyPI, its metadata should explicitly declare newton as a dependency.

maybe the per-package pyproject.toml files could be constructed from the central one?

Regarding the central location, I see that as something serving repository development rather than package distribution. It is useful for maintaining a consistent development environment, but it should not dictate the structure of the individual packages. The individual packages should also not depend on isaaclab-dev, since that package is not intended for downstream distribution.

Instead, isaaclab-dev could collect the individual packages and provide a resolved development environment (e.g., through a workspace/lock file). This would allow you to:

  1. keep package metadata correct and independent
  2. avoid unnecessary strict pins in individual packages
  3. introduce strict pinning here, e.g. for isaacsim interoperability
  4. provide developers with a known-good environment

My preference would be:

  • Individual packages specify dependencies with >= constraints (and upper bounds only when strictly required, e.g. a new major release that already broke assumptions).
  • isaaclab-dev is structured as a workspace that collects all packages and generates the lock file (workspaces seems the perfect use case here).
  • If you want to ensure shared dependencies use exactly matching constraints across packages, a small validation python script in pre-commit / CI could parse the pyproject files and check for inconsistencies.

In general, I think it is better for individual packages to be under-constrained rather than over-constrained. Downstream users can always add stricter pins in their environment, but overly strict package requirements are difficult to override and can prevent otherwise valid installations.

Comment on lines 30 to 32
play = "isaaclab.cli:play"
train = "isaaclab.cli:train"
train_multigpu = "isaaclab.cli:train_multigpu"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I already commented in the previous PR, these generic executable names are problematic in larger downstream environments.

I would suggest to refactor these play/train commands as subcommands of isaaclab, such as:

  • isaaclab [...]
  • isaaclab play [...]
  • isaaclab train [...]
  • isaaclab train --multi-gpu [...]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is the concern here around the global definition of train/play in an environment?

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the main concern is the global definition of these commands in an environment.

isaaclab might be installed in a virtualenv or a larger conda environment together with many other packages, including ML/RL frameworks such as PyTorch, Lightning, Ray, etc. In these cases, the environment's bin/ directory contains entry points from all installed packages. Adding generic executables such as play or train makes the namespace ambiguous and can easily lead to conflicts with other projects.

This also creates problems for downstream packagers. For example, if someone wanted to create a python3-isaaclab package for Ubuntu/Debian, generic binaries like train or play would likely not be acceptable in /usr/bin and would need to be renamed or wrapped anyway.

This is admittedly an extreme example, but it highlights the underlying issue: these names do not uniquely identify IsaacLab functionality. Since you already have a natural namespace available through an isaaclab CLI, I think it would be cleaner and more future-proof to expose these as subcommands:

isaaclab play [...]
isaaclab train [...]
isaaclab train --multi-gpu [...]

Given the growing adoption of IsaacLab, having a single, well-defined command namespace would also make it easier for users and downstream maintainers to integrate it into larger environments.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, that's a good point, we should not pollute global namespace in any environment

Comment thread pyproject.toml
# Omniverse renderer / physics backends. Installable separately or together via
# the ``ov[ovphysx]`` / ``ov[ovrtx]`` / ``ov[all]`` install selectors. Pins mirror
# ``[tool.isaaclab.versions]``.
ov = ["ovphysx==0.4.13"]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this be ovphysx instead?

Comment on lines +31 to +35
# The base contrib package is installed with the core Isaac Lab packages.
# Install its optional dependencies (e.g., for RLinf VLA post-training) with pip:
pip install "ray[default]>=2.47.0" "av>=12.3.0" "numpydantic>=1.7.0" \
"albumentations>=1.4.18" decord2 "dm_tree>=0.1.8" "diffusers>=0.35.0" \
"timm>=1.0.14" "peft>=0.17.0" pandas

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^

# Install with optional extras (e.g., for RLinf VLA post-training)
uv pip install -e "source/isaaclab_contrib[rlinf]"
# The base contrib package is installed with the core Isaac Lab packages.
# Install its optional dependencies (e.g., for RLinf VLA post-training) with pip:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this feels a lot less user friendly. are we able to reference the rlinf option from pyproject directly somehow?

" ov[ovrtx|ovphysx|all]\n"
" rl[rsl-rl|skrl|sb3|rl-games] (default: all)\n"
" visualizer[kit|newton|rerun|viser] (default: all)\n"
" visualizer[kit|rerun|viser] (default: all)\n"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is newton still a valid option? it still seems to be listed in the selective install docs

Comment on lines +19 to +22
# Third-party requirements are centralized in the root pyproject.toml
# (single source of truth for the uv workspace, the wheel builder, and the
# ./isaaclab.sh -i install CLI).
dependencies = []

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's a valid point. I think part of what we wanted to achieve here is that we can have a central location that guards the version pinning for our dependencies so that we don't end up with multiple packages specifying the same dependency, but could easily misalign in versioning because someone forgot to update it.

perhaps there's a better way to handle both of these needs. ideally we can have a central place that acts as the source of truth for all version pinning, and each package will hold its own list of dependencies and pull the versioning from the central location. maybe the per-package pyproject.toml files could be constructed from the central one?

Comment on lines 30 to 32
play = "isaaclab.cli:play"
train = "isaaclab.cli:train"
train_multigpu = "isaaclab.cli:train_multigpu"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is the concern here around the global definition of train/play in an environment?

@kellyguo11 kellyguo11 moved this to In review in Isaac Lab Jun 26, 2026
@kellyguo11 kellyguo11 moved this from In review to In progress in Isaac Lab Jun 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation infrastructure isaac-mimic Related to Isaac Mimic team

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

7 participants