Adds quick installation and supporting doc pages by rdsa-nv · Pull Request #5002 · isaac-sim/IsaacLab

rdsa-nv · 2026-03-13T14:59:51Z

Summary

Adds a concise Quick Installation page (quick_installation.rst) with copy-paste install + run steps
Adds installation_guide.rst, configurations.rst, and robots.rst reference pages
Registers all new pages in the Getting Started toctree

Split from #4966 per reviewer feedback (docs-only changes).

Test plan

Build docs with ./isaaclab.sh -d and verify new pages render correctly
Verify toctree links resolve without warnings
Confirm quickstart.rst (upstream) is unchanged

Add a concise Quick Installation guide alongside the existing Quickstart Guide, plus installation_guide, configurations, and robots reference pages in the Getting Started toctree.

greptile-apps · 2026-03-13T15:03:21Z

Greptile Summary

This docs-only PR adds five new reference pages to the Isaac Lab documentation — quick_installation.rst, installation_guide.rst, configurations.rst, robots.rst, and an orphan installation.md — and registers the first four in the "Getting Started" toctree in docs/index.rst. The pages provide a quick-start install flow, optional add-on paths, RL/configclass concepts, and a robot configuration reference, filling a gap that previously required users to navigate scattered existing docs.

Key issues found:

installation_guide.rst has a broken RST heading hierarchy: "Selective Install", "Running Installation Tests", and "Troubleshooting" use - as their underline after ^ is already established as heading level 2, causing Sphinx to nest them as sub-subsections of neighboring sections rather than rendering them as independent peers.
configurations.rst references the script directory as isaaclab/scripts/reinforcement_learning, but the actual path in the repository is scripts/reinforcement_learning (no isaaclab/ prefix); users following the instructions will not find the files at the stated location.
robots.rst contains a typo — "actuation model determined by the joint time" should read "joint type".
quick_installation.rst splits a sequential four-step install flow across four separate code blocks, making it harder to copy-paste the full setup in one shot.

Confidence Score: 3/5

Safe to merge after addressing the broken heading hierarchy in installation_guide.rst and the incorrect script path in configurations.rst — both will produce visibly wrong rendered output.
The PR is documentation-only with no runtime impact, but two of the new pages contain factual errors (wrong path, malformed RST structure) that would mislead users reading the rendered docs. The RST heading issue in particular will produce an incorrect sidebar/TOC structure without any Sphinx build warning, making it easy to miss without a careful visual inspection.
Pay close attention to docs/source/setup/installation_guide.rst (heading levels) and docs/source/setup/configurations.rst (script path in prose).

Important Files Changed

Filename	Overview
docs/index.rst	Adds four new pages to the "Getting Started" toctree; ordering and syntax are correct.
docs/source/setup/quick_installation.rst	New quick-start page; content is correct but the four sequential install steps are split into separate code blocks, making one-shot copy-paste harder for users.
docs/source/setup/installation_guide.rst	New installation reference page; RST heading hierarchy is broken — "Selective Install", "Running Installation Tests", and "Troubleshooting" use `-` after `^` is established as level 2, rendering them as sub-subsections of adjacent sections rather than as top-level peers.
docs/source/setup/configurations.rst	New configurations guide; contains an incorrect script path in prose ("isaaclab/scripts/reinforcement_learning" instead of the correct "scripts/reinforcement_learning").
docs/source/setup/robots.rst	New robots reference page; contains a typo — "actuation model determined by the joint time" should read "joint type".
docs/source/setup/installation.md	New Markdown installation guide marked `orphan: true`; not linked from any toctree or new page, so it is reachable only by direct URL — this appears intentional.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[docs/index.rst\nGetting Started toctree] --> B[quickstart.rst\nexisting]
    A --> C[quick_installation.rst\nnew — install + run steps]
    A --> D[installation_guide.rst\nnew — optional add-ons,\nselective install, troubleshooting]
    A --> E[configurations.rst\nnew — RL concepts,\nenvironments, configclass]
    A --> F[robots.rst\nnew — robot config reference]
    A --> G[own-project/index ...]

    C -->|references| D
    E -->|cross-ref :ref:| F
    D2[installation.md\northan: true\nnot in toctree] -.->|direct URL only| D

_{Last reviewed commit: 6a27e95}

greptile-apps · 2026-03-13T15:03:24Z

docs/source/setup/robots.rst

+are what informs vectorization, and it's the ``InitialStateCfg`` that describes the state of the joints of our robot when it gets created in each environment. The
+``ImplicitActuatorCfg`` defines the joints of the robot using the default actuation model determined by the joint time.  Not all joints need to be actuated, but you


Typo: "joint time" should be "joint type"

The sentence reads "the default actuation model determined by the joint time", but the correct phrase here is "joint type". The ImplicitActuatorCfg uses the joint's physics properties (its type), not a time value, to determine how actuation is modeled.

Suggested change

are what informs vectorization, and it's the ``InitialStateCfg`` that describes the state of the joints of our robot when it gets created in each environment. The

``ImplicitActuatorCfg`` defines the joints of the robot using the default actuation model determined by the joint time. Not all joints need to be actuated, but you

The

``ImplicitActuatorCfg`` defines the joints of the robot using the default actuation model determined by the joint type. Not all joints need to be actuated, but you

greptile-apps · 2026-03-13T15:03:26Z

docs/source/setup/configurations.rst

+The various backends of Isaac Lab are accessed through their corresponding ``train.py`` and ``play.py`` scripts located in the ``isaaclab/scripts/reinforcement_learning`` directory.
+Invoking these scripts will require a **Task Name** and a corresponding **Entry Point** to the gymnasium API. For example


Incorrect script path in prose description

The text says scripts are located in the isaaclab/scripts/reinforcement_learning directory, but the actual repository path (confirmed from the codebase structure) is scripts/reinforcement_learning. The isaaclab/ prefix does not exist and would mislead users trying to find the scripts.

Suggested change

The various backends of Isaac Lab are accessed through their corresponding ``train.py`` and ``play.py`` scripts located in the ``isaaclab/scripts/reinforcement_learning`` directory.

Invoking these scripts will require a **Task Name** and a corresponding **Entry Point** to the gymnasium API. For example

The various backends of Isaac Lab are accessed through their corresponding ``train.py`` and ``play.py`` scripts located in the ``scripts/reinforcement_learning`` directory.

greptile-apps · 2026-03-13T15:03:27Z

docs/source/setup/installation_guide.rst

+Selective Install
+-------------------
+


RST heading hierarchy creates incorrect TOC structure

Because ^ was introduced first (for the three "Isaac Sim" / "OVRTX" sections) and establishes heading level 2, any subsequent use of - becomes heading level 3. This means:

Selective Install (line 55, -) is rendered as a subsection of "OVRTX Rendering", not as a sibling.

Running Installation Tests (line 120, -) and Troubleshooting (line 128, -) are rendered as subsections of "Conda Alternative", not as top-level sections.

The sections Selective Install, Conda Alternative, Running Installation Tests, and Troubleshooting all appear to be intended as level-2 siblings of the Isaac Sim sections. To achieve this, change their underlines from --- to ^^^:

Selective Install ^^^^^^^^^^^^^^^^^

Running Installation Tests ^^^^^^^^^^^^^^^^^^^^^^^^^^

Troubleshooting ^^^^^^^^^^^^^^^

greptile-apps · 2026-03-13T15:03:28Z

docs/source/setup/quick_installation.rst

+.. code-block:: bash
+
+   # Install uv
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+
+.. code-block:: bash
+
+   # Clone Isaac Lab
+   git clone https://github.com/isaac-sim/IsaacLab.git
+   cd IsaacLab
+
+.. code-block:: bash
+
+   # Create environment and install
+   uv venv .venv --python 3.12
+   source .venv/bin/activate
+   ./isaaclab.sh -i
+
+.. code-block:: bash
+
+   # Run training
+   ./isaaclab.sh -p scripts/benchmarks/benchmark_rlgames.py \
+     --task=Isaac-Repose-Cube-Shadow-Vision-Benchmark-Direct-v0 \
+     --headless --enable_cameras --num_envs=1225 --max_iterations=10 \
+     presets=newton,newton_renderer,depth


Fragmented install steps hinder one-shot copy-paste

The four sequential installation steps are split across four separate .. code-block:: bash directives. Users following a quick-start guide typically expect to copy and run a single block. Consolidating these into one block (as done in installation.md) avoids confusion about ordering and makes it easier to automate:

.. code-block:: bash # Install uv curl -LsSf https://astral.sh/uv/install.sh | sh # Clone Isaac Lab git clone https://github.com/isaac-sim/IsaacLab.git cd IsaacLab # Create environment and install uv venv .venv --python 3.12 source .venv/bin/activate ./isaaclab.sh -i # Run training ./isaaclab.sh -p scripts/benchmarks/benchmark_rlgames.py \ --task=Isaac-Repose-Cube-Shadow-Vision-Benchmark-Direct-v0 \ --headless --enable_cameras --num_envs=1225 --max_iterations=10 \ presets=newton,newton_renderer,depth

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

AntoineRichard · 2026-03-13T15:17:42Z

@rdsa-nv it is sage to close : #4966 now right? Also I had a bunch of comments there about how these new installation doc mesh with the old one. Would you have time to look at them?

AntoineRichard

Need to fix:

/home/runner/work/IsaacLab/IsaacLab/docs/source/setup/installation_guide.rst:4: WARNING: Title underline too short.

Rather than doing:

.. note::

   **Isaac Lab 3.0 supports kit-less installation.** You can install and use Isaac Lab with the
   Newton physics backend *without* installing Isaac Sim. Simply clone Isaac Lab and run:

   .. code-block:: bash

      ./isaaclab.sh --install   # or ./isaaclab.sh -i

   This installs the core Isaac Lab packages and the Newton physics backend. Isaac Sim is **not**
   required for this mode. See `Kit-less Installation`_ below for which features are available
   without Isaac Sim.

   When you need full simulation features — including PhysX, ROS, URDF/MJCF
   importers — install Isaac Sim via pip (see the
   :doc:`pip_installation` guide).

In docs/source/setup/installation/index.rst we could link the quick installation guide.

AntoineRichard · 2026-03-13T15:49:00Z

docs/source/how-to/robots.rst

docs/source/how-to

AntoineRichard · 2026-03-13T15:50:36Z

docs/source/setup/installation.md

Remove the md file

AntoineRichard · 2026-03-13T15:51:58Z

docs/source/setup/installation_guide.rst

+
+- **OS:** Ubuntu 22.04+ (Linux x86_64) or Windows 11 (x86_64)
+- **RAM:** 32 GB or more
+- **GPU:** NVIDIA GPU with 16 GB+ VRAM (for Kit/RTX rendering)


GPU: NVIDIA GPU with 16 GB+ VRAM recommended for Kit/RTX rendering

AntoineRichard · 2026-03-13T15:52:23Z

docs/source/setup/installation_guide.rst

+- **RAM:** 32 GB or more
+- **GPU:** NVIDIA GPU with 16 GB+ VRAM (for Kit/RTX rendering)
+- **Drivers:** NVIDIA driver 580.65.06+ (Linux), 580.88+ (Windows)
+- **Python:** 3.11 (Isaac Sim 5.x) or 3.12 (Isaac Sim 6.x, when available)


Python: 3.12 (Isaac Sim 6.x, when available)

AntoineRichard · 2026-03-13T15:53:44Z

docs/source/setup/installation_guide.rst

+Isaac Sim (Kit/RTX rendering)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   ./isaaclab.sh -i isaacsim


Could have a bit more text to introduce what the user needs to do. And then point to the complete doc if they want to do something more complex.

AntoineRichard · 2026-03-13T16:00:13Z

docs/source/setup/installation_guide.rst

+Conda Alternative (Kit Path Only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   conda create -n env_isaaclab python=3.12
+   conda activate env_isaaclab
+   pip install "isaacsim[all,extscache]==6.0.0" --extra-index-url https://pypi.nvidia.com
+   pip install -U torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128
+   git clone https://github.com/isaac-sim/IsaacLab.git && cd IsaacLab
+   ./isaaclab.sh -i


Do we want to keep Conda? @kellyguo11

AntoineRichard · 2026-03-13T16:00:58Z

docs/source/setup/installation_guide.rst

+Troubleshooting
+-------------------
+
+``ModuleNotFoundError: No module named 'pip'``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Your venv was created without pip. The install system auto-detects and uses
+``uv pip`` when pip is absent, so this error should no longer occur with the
+latest Isaac Lab.
+
+``ModuleNotFoundError: No module named 'isaacsim'``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You are running a script that requires Isaac Sim, but it is not installed.
+Either:
+
+- Install Isaac Sim: ``./isaaclab.sh -i isaacsim``, or
+- Use a Newton-based task with ``presets=newton --visualizer newton`` (Kit-less path)
+
+``ModuleNotFoundError: No module named 'isaaclab_physx'`` or ``'isaaclab_ov'``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These config packages are auto-installed by ``./isaaclab.sh -i``. If using a
+selective install, re-run with the default ``./isaaclab.sh -i`` to get all
+packages.
+
+``ModuleNotFoundError: No module named 'isaaclab_assets'``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Include ``assets`` in your install command, or use ``./isaaclab.sh -i`` to install
+everything.
+
+``ModuleNotFoundError: No module named 'rsl_rl'``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Include the RL framework: ``./isaaclab.sh -i rsl_rl``, or use
+``./isaaclab.sh -i`` to install all frameworks.
+
+Crash in ``libusd_tf`` / USD Symbol Collision with OVRTX
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you see a crash involving ``libusd_tf-*.so`` and conflicting USD versions
+(e.g. ``pxrInternal_v0_25_5`` vs ``pxrInternal_v0_25_11``):
+
+1. Ensure ``LD_PRELOAD`` is set to ovrtx's ``libcarb.so`` (see OVRTX section)
+2. Ensure ``isaacsim`` / ``omniverse-kit`` is **not** installed in the same
+   environment — their bundled USD libraries conflict with ovrtx's
+
+Visualizer Not Appearing
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If ``--visualizer newton`` shows no window, you may be missing ``imgui-bundle``:
+
+.. code-block:: bash
+
+   uv pip install imgui-bundle
+
+For ``viser``, check the terminal for a URL (e.g. ``http://localhost:8012``).
+
+``GLIBC Version Too Old``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Isaac Sim pip packages require GLIBC 2.35+. Check with ``ldd --version``.
+Ubuntu 22.04+ satisfies this. For older distributions, use the
+`binary installation <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_workstation.html>`_
+method for Isaac Sim.


move the troubleshooting. And link troubleshooting instead.

AntoineRichard · 2026-03-13T16:03:54Z

docs/source/setup/quick_installation.rst

+
+The ``presets=`` Hydra override selects the physics backend and renderer at runtime:
+
+.. code-block:: bash
+
+   # Newton (Kit-less)
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+     --task Isaac-Cartpole-Direct-v0 \
+     --num_envs 4096 \
+     presets=newton \
+     --visualizer newton
+
+   # PhysX (Kit — requires Isaac Sim)
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+     --task Isaac-Cartpole-Direct-v0 \
+     --num_envs 4096 \
+     presets=physx
+
+   # Newton with a specific visualizer
+   ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \
+     --task Isaac-Cartpole-Direct-v0 \
+     --num_envs 4096 \
+     presets=newton \
+     --visualizer viser
+
+Kit-less visualizer options: ``newton``, ``rerun``, ``viser``. Multiple can be
+combined: ``--visualizer newton,rerun``.


Link the hydra preset doc.

Might be good to link do to explain how the backend switching works, and how the maybe some other doc about env training, and the visualizer doc + render as well.

AntoineRichard · 2026-03-13T16:11:40Z

docs/source/setup/installation_guide.rst

THis one we need to check what's the gap between it and the other installation files/guidelines that already exists, and modify these, rather than keeping this file.

AntoineRichard · 2026-03-13T16:12:03Z

docs/index.rst

This will need to be adjusted.

ooctipus

lgtm

looks like all changes requested is applied

## Summary - Adds a concise **Quick Installation** page (`quick_installation.rst`) with copy-paste install + run steps - Adds `installation_guide.rst`, `configurations.rst`, and `robots.rst` reference pages - Registers all new pages in the Getting Started toctree Split from isaac-sim#4966 per reviewer feedback (docs-only changes). ## Test plan - [ ] Build docs with `./isaaclab.sh -d` and verify new pages render correctly - [ ] Verify toctree links resolve without warnings - [ ] Confirm `quickstart.rst` (upstream) is unchanged --------- Co-authored-by: Antoine Richard <antoiner@nvidia.com>

Add quick installation and supporting doc pages

6a27e95

Add a concise Quick Installation guide alongside the existing Quickstart Guide, plus installation_guide, configurations, and robots reference pages in the Getting Started toctree.

rdsa-nv requested review from Mayankm96, jtigue-bdai and kellyguo11 as code owners March 13, 2026 14:59

github-actions bot added the documentation Improvements or additions to documentation label Mar 13, 2026

rdsa-nv mentioned this pull request Mar 13, 2026

Add simple quick installation docs #4966

Closed

7 tasks

greptile-apps bot reviewed Mar 13, 2026

View reviewed changes

AntoineRichard previously requested changes Mar 13, 2026

View reviewed changes

AntoineRichard and others added 3 commits March 13, 2026 17:59

after a pass with claude

63e2e3c

add additional configs to docs

f9f97dc

Merge branch 'develop' into user/ruben/docs-quickstart

ccdae44

rdsa-nv requested a review from AntoineRichard March 14, 2026 19:43

ooctipus approved these changes Mar 14, 2026

View reviewed changes

ooctipus changed the title ~~Add quick installation and supporting doc pages~~ Adds quick installation and supporting doc pages Mar 14, 2026

ooctipus merged commit 5139203 into isaac-sim:develop Mar 14, 2026
8 checks passed

		are what informs vectorization, and it's the ``InitialStateCfg`` that describes the state of the joints of our robot when it gets created in each environment. The
		``ImplicitActuatorCfg`` defines the joints of the robot using the default actuation model determined by the joint time. Not all joints need to be actuated, but you

		The various backends of Isaac Lab are accessed through their corresponding ``train.py`` and ``play.py`` scripts located in the ``isaaclab/scripts/reinforcement_learning`` directory.
		Invoking these scripts will require a Task Name and a corresponding Entry Point to the gymnasium API. For example

Conversation

rdsa-nv commented Mar 13, 2026

Summary

Test plan

Uh oh!

greptile-apps bot commented Mar 13, 2026

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Flowchart

Uh oh!

greptile-apps bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

AntoineRichard commented Mar 13, 2026

Uh oh!

AntoineRichard left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ooctipus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants