Installation using Isaac Lab Pip Packages
=========================================

From Isaac Lab 2.0, pip packages are provided to install both Isaac Sim and Isaac Lab extensions from pip.
Note that this installation process is only recommended for advanced users working on additional extension projects
that are built on top of Isaac Lab. Isaac Lab pip packages **does not** include any standalone python scripts for
training, inferencing, or running standalone workflows such as demos and examples. Therefore, users are required
to define their own runner scripts when installing Isaac Lab from pip.

To learn about how to set up your own project on top of Isaac Lab, please see :ref:`template-generator`.

.. note::

   Currently, we only provide pip packages for every major release of Isaac Lab.
   For example, we provide the pip package for release 2.1.0 and 2.2.0, but not 2.1.1.
   In the future, we will provide pip packages for every minor release of Isaac Lab.

.. include:: include/pip_python_virtual_env.rst

Installing Isaac Lab
~~~~~~~~~~~~~~~~~~~~

The ``isaaclab`` package provides optional extras to install Isaac Sim and individual
Isaac Lab sub-packages:

.. list-table::
   :header-rows: 1
   :widths: 15 55

   * - Extra
     - What it installs
   * - ``isaacsim``
     - Isaac Sim (``isaacsim[all,extscache]==X.X.X``) from `pypi.nvidia.com <https://pypi.nvidia.com>`_
   * - ``assets``
     - ``isaaclab_assets``
   * - ``physx``
     - ``isaaclab_physx``
   * - ``contrib``
     - ``isaaclab_contrib``
   * - ``mimic``
     - ``isaaclab_mimic``
   * - ``newton``
     - ``isaaclab_newton``
   * - ``rl``
     - ``isaaclab_rl``
   * - ``tasks``
     - ``isaaclab_tasks``
   * - ``teleop``
     - ``isaaclab_teleop``
   * - ``all``
     - All of the above sub-packages (does **not** include ``isaacsim``)

.. tab-set::

   .. tab-item:: uv

      .. code-block:: bash

         # Isaac Lab only
         uv pip install isaaclab # latest version
         uv pip install isaaclab==3.0.0 # specific version

         # Isaac Lab + Isaac Sim
         uv pip install "isaaclab[isaacsim]"

         # Isaac Lab + specific sub-package(s)
         uv pip install "isaaclab[assets]"
         uv pip install "isaaclab[rl,tasks]"

         # Isaac Lab + Isaac Sim + all sub-packages
         uv pip install "isaaclab[isaacsim,all]"

   .. tab-item:: pip

      .. code-block:: bash

         # Isaac Lab only
         pip install isaaclab # latest version
         pip install isaaclab==3.0.0 # specific version

         # Isaac Lab + Isaac Sim
         pip install "isaaclab[isaacsim]" --extra-index-url https://pypi.nvidia.com

         # Isaac Lab + specific sub-package(s)
         pip install "isaaclab[assets]"
         pip install "isaaclab[rl,tasks]"

         # Isaac Lab + Isaac Sim + all Isaac Lab sub-packages
         pip install "isaaclab[isaacsim,all]" --extra-index-url https://pypi.nvidia.com

Installing dependencies
~~~~~~~~~~~~~~~~~~~~~~~

-  Install a CUDA-enabled PyTorch 2.10.0 build that matches your system architecture:

   .. tab-set::
      :sync-group: pip-platform

      .. tab-item:: :icon:`fa-brands fa-linux` Linux (x86_64)
         :sync: linux-x86_64

         .. code-block:: bash

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

      .. tab-item:: :icon:`fa-brands fa-windows` Windows (x86_64)
         :sync: windows-x86_64

         .. code-block:: bash

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

      .. tab-item:: :icon:`fa-brands fa-linux` Linux (aarch64)
         :sync: linux-aarch64

         .. code-block:: bash

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

         .. note::

            On aarch64 (e.g., DGX Spark), ``imgui-bundle`` and ``quadprog`` must be compiled from source because no
            pre-built wheel is available. Install the required Python, OpenGL, and X11 development packages
            **before** installing Isaac Lab:

            .. code-block:: bash

               sudo apt install python3.12-dev libgl1-mesa-dev libx11-dev libxcursor-dev libxi-dev libxinerama-dev libxrandr-dev

         .. note::

            After installing Isaac Lab on aarch64, you may encounter warnings such as:

            .. code-block:: none

               ERROR: ld.so: object '...torch.libs/libgomp-XXXX.so.1.0.0' cannot be preloaded: ignored.

            This occurs when both the system and PyTorch ``libgomp`` (GNU OpenMP) libraries are preloaded.
            Isaac Sim expects the **system** OpenMP runtime, while PyTorch sometimes bundles its own.

            To fix this, unset any existing ``LD_PRELOAD`` and set it to use the system library only:

            .. code-block:: bash

               unset LD_PRELOAD
               export LD_PRELOAD="$LD_PRELOAD:/lib/aarch64-linux-gnu/libgomp.so.1"

            This ensures the correct ``libgomp`` library is preloaded for both Isaac Sim and Isaac Lab,
            removing the preload warnings during runtime.

         .. note::

            On aarch64, you may encounter the following error when importing ``omni.client`` or ``torch``:

            .. code-block:: none

               ImportError: .../libcarb.so: cannot allocate memory in static TLS block

            This happens because ``libcarb.so`` uses the *initial-exec* TLS model, and
            the dynamic linker's fixed-size TLS surplus is exhausted by the time it is loaded.
            To fix this, preload ``libcarb.so`` before launching Python:

            .. code-block:: bash

               export LD_PRELOAD=$(python -c "import sys,os;[print(os.path.join(p,'omni','client','libcarb.so')) for p in sys.path if os.path.isfile(os.path.join(p,'omni','client','libcarb.so'))]" 2>/dev/null | head -1)${LD_PRELOAD:+:$LD_PRELOAD}

            When using ``./isaaclab.sh -p``, this is handled automatically.
            When using a conda environment,
            the preload is set up via the conda activation hook.

-  If you want to use ``rl_games`` for training and inferencing, install
   its Python 3.11+ enabled fork:

   .. code-block:: none

      pip install git+https://github.com/isaac-sim/rl_games.git@python3.11

.. include:: include/pip_verify_isaacsim.rst

Running Isaac Lab Scripts
~~~~~~~~~~~~~~~~~~~~~~~~~

By following the above scripts, your Python environment should now have access to all of the Isaac Lab extensions.
To run a user-defined script for Isaac Lab, simply run

.. code:: bash

    python my_awesome_script.py

Generating VS Code Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Due to the structure resulting from the installation, VS Code IntelliSense (code completion, parameter info
and member lists, etc.) will not work by default. To set it up (define the search paths for import resolution,
the path to the default Python interpreter, and other settings), for a given workspace folder,
run the following command:

.. code-block:: bash

   python -m isaaclab --generate-vscode-settings


.. warning::

   The command will generate a ``.vscode/settings.json`` file in the workspace folder.
   If the file already exists, it will be overwritten (a confirmation prompt will be shown first).