Adds uv support as an alternative to conda in isaaclab.sh (#3172)

# Description

This PR adds support for uv as an alternative to conda or venv for
managing virtual environments and adds corresponding support for uv pip
for managing python dependencies. uv and uv pip is significantly faster
than conda and has many useful tools.

If users wish to use the uv workflow they will need to have uv
installed, but otherwise no additional dependencies are added.

Docs should be updated to describe this option. There may need to be
more work done to clean when deactivating the environment. Uv does not
support pre and post activation hooks like conda so cleaning up the
environment variables is slightly more tricky. I would greatly
appreciate feedback to improve this workflow!

Fixes #3408

## Type of change

- New feature (non-breaking change which adds functionality)
- This change requires a documentation update


## Checklist

- [X] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [X] 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
- [X] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

---------

Signed-off-by: Kyle Morgenstein <[email protected]>
Signed-off-by: Mayank Mittal <[email protected]>
Co-authored-by: Mayank Mittal <[email protected]>

Author: KyleM73

docs/licenses/dependencies/uv-license.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Astral Software Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/source/overview/developer-guide/vs_code.rst

@@ -69,7 +69,7 @@ python executable provided by Omniverse. This is specified in the
       "python.defaultInterpreterPath": "${workspaceFolder}/_isaac_sim/python.sh",
    }
 
-If you want to use a different python interpreter (for instance, from your conda environment),
+If you want to use a different python interpreter (for instance, from your conda or uv environment),
 you need to change the python interpreter used by selecting and activating the python interpreter
 of your choice in the bottom left corner of VSCode, or opening the command palette (``Ctrl+Shift+P``)
 and selecting ``Python: Select Interpreter``.

docs/source/overview/own-project/template.rst

@@ -33,7 +33,7 @@ Running the template generator
 ------------------------------
 
 Install Isaac Lab by following the `installation guide <../../setup/installation/index.html>`_.
-We recommend using conda installation as it simplifies calling Python scripts from the terminal.
+We recommend using conda or uv installation as it simplifies calling Python scripts from the terminal.
 
 Then, run the following command to generate a new external project or internal task:
 

docs/source/setup/installation/binaries_installation.rst

@@ -213,6 +213,7 @@ Clone the Isaac Lab repository into your workspace:
                -d, --docs           Build the documentation from source using sphinx.
                -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
+               -u, --uv [NAME]      Create the uv environment for Isaac Lab. Default name is 'env_isaaclab'.
 
       .. tab-item:: :icon:`fa-brands fa-windows` Windows
          :sync: windows
@@ -234,6 +235,7 @@ Clone the Isaac Lab repository into your workspace:
                -d, --docs           Build the documentation from source using sphinx.
                -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
+               -u, --uv [NAME]      Create the uv environment for Isaac Lab. Default name is 'env_isaaclab'.
 
 
 Creating the Isaac Sim Symbolic Link
@@ -268,6 +270,57 @@ to index the python modules and look for extensions shipped with Isaac Sim.
          mklink /D _isaac_sim path_to_isaac_sim
          :: For example: mklink /D _isaac_sim C:/isaacsim
 
+Setting up the uv environment (optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. attention::
+   This step is optional. If you are using the bundled python with Isaac Sim, you can skip this step.
+
+The executable ``isaaclab.sh`` automatically fetches the python bundled with Isaac
+Sim, using ``./isaaclab.sh -p`` command (unless inside a virtual environment). This executable
+behaves like a python executable, and can be used to run any python script or
+module with the simulator. For more information, please refer to the
+`documentation <https://docs.isaacsim.omniverse.nvidia.com/latest/python_scripting/manual_standalone_python.html>`__.
+
+To install ``uv``, please follow the instructions `here <https://docs.astral.sh/uv/getting-started/installation/>`__.
+You can create the Isaac Lab environment using the following commands.
+
+.. tab-set::
+   :sync-group: os
+
+   .. tab-item:: :icon:`fa-brands fa-linux` Linux
+      :sync: linux
+
+      .. code:: bash
+
+         # Option 1: Default name for uv environment is 'env_isaaclab'
+         ./isaaclab.sh --uv  # or "./isaaclab.sh -u"
+         # Option 2: Custom name for uv environment
+         ./isaaclab.sh --uv my_env  # or "./isaaclab.sh -u my_env"
+
+   .. tab-item:: :icon:`fa-brands fa-windows` Windows
+      :sync: windows
+
+      .. code:: batch
+
+         :: Option 1: Default name for uv environment is 'env_isaaclab'
+         isaaclab.bat --uv  :: or "isaaclab.bat -u"
+         :: Option 2: Custom name for uv environment
+         isaaclab.bat --uv my_env  :: or "isaaclab.bat -u my_env"
+
+
+Once created, be sure to activate the environment before proceeding!
+
+.. code:: bash
+
+   source ./env_isaaclab/bin/activate  # or "source ./my_env/bin/activate"
+
+Once you are in the virtual environment, you do not need to use ``./isaaclab.sh -p`` / ``isaaclab.bat -p``
+to run python scripts. You can use the default python executable in your environment
+by running ``python`` or ``python3``. However, for the rest of the documentation,
+we will assume that you are using ``./isaaclab.sh -p`` / ``isaaclab.bat -p`` to run python scripts. This command
+is equivalent to running ``python`` or ``python3`` in your virtual environment.
+
 
 Setting up the conda environment (optional)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -427,8 +480,8 @@ On Windows machines, please terminate the process from Command Prompt using
 
 If you see this, then the installation was successful! |:tada:|
 
-If you see an error ``ModuleNotFoundError: No module named 'isaacsim'``, ensure that the conda environment is activated
-and ``source _isaac_sim/setup_conda_env.sh`` has been executed.
+If you see an error ``ModuleNotFoundError: No module named 'isaacsim'``, ensure that the conda or uv environment is activated
+and ``source _isaac_sim/setup_conda_env.sh`` has been executed (for uv as well).
 
 
 Train a robot!

docs/source/setup/installation/isaaclab_pip_installation.rst

@@ -25,6 +25,31 @@ To learn about how to set up your own project on top of Isaac Lab, see :ref:`tem
             conda create -n env_isaaclab python=3.11
             conda activate env_isaaclab
 
+      .. tab-item:: uv environment
+
+         .. tab-set::
+            :sync-group: os
+
+            .. tab-item:: :icon:`fa-brands fa-linux` Linux
+               :sync: linux
+
+               .. code-block:: bash
+
+                  # create a virtual environment named env_isaaclab with python3.11
+                  uv venv --python 3.11 env_isaaclab
+                  # activate the virtual environment
+                  source env_isaaclab/bin/activate
+
+            .. tab-item:: :icon:`fa-brands fa-windows` Windows
+               :sync: windows
+
+               .. code-block:: batch
+
+                  # create a virtual environment named env_isaaclab with python3.11
+                  uv venv --python 3.11 env_isaaclab
+                  # activate the virtual environment
+                  env_isaaclab\Scripts\activate
+
       .. tab-item:: venv environment
 
          .. tab-set::
@@ -70,6 +95,10 @@ To learn about how to set up your own project on top of Isaac Lab, see :ref:`tem
 
             python -m pip install --upgrade pip
 
+.. note::
+
+   If you use uv, replace ``pip`` with ``uv pip``.
+
 
 -  Next, install a CUDA-enabled PyTorch 2.7.0 build for CUDA 12.8.
 

docs/source/setup/installation/pip_installation.rst

@@ -49,6 +49,31 @@ If you encounter any issues, please report them to the
             conda create -n env_isaaclab python=3.11
             conda activate env_isaaclab
 
+      .. tab-item:: uv environment
+
+         .. tab-set::
+            :sync-group: os
+
+            .. tab-item:: :icon:`fa-brands fa-linux` Linux
+               :sync: linux
+
+               .. code-block:: bash
+
+                  # create a virtual environment named env_isaaclab with python3.11
+                  uv venv --python 3.11 env_isaaclab
+                  # activate the virtual environment
+                  source env_isaaclab/bin/activate
+
+            .. tab-item:: :icon:`fa-brands fa-windows` Windows
+               :sync: windows
+
+               .. code-block:: batch
+
+                  # create a virtual environment named env_isaaclab with python3.11
+                  uv venv --python 3.11 env_isaaclab
+                  # activate the virtual environment
+                  env_isaaclab\Scripts\activate
+
       .. tab-item:: venv environment
 
          .. tab-set::
@@ -94,6 +119,9 @@ If you encounter any issues, please report them to the
 
             python -m pip install --upgrade pip
 
+.. note::
+
+   If you use uv, replace ``pip`` with ``uv pip``.
 
 -  Next, install a CUDA-enabled PyTorch 2.7.0 build.
 
@@ -216,6 +244,7 @@ Clone the Isaac Lab repository into your workspace:
                -d, --docs           Build the documentation from source using sphinx.
                -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
+               -u, --uv [NAME]      Create the uv environment for Isaac Lab. Default name is 'env_isaaclab'.
 
       .. tab-item:: :icon:`fa-brands fa-windows` Windows
          :sync: windows
@@ -237,6 +266,7 @@ Clone the Isaac Lab repository into your workspace:
                -d, --docs           Build the documentation from source using sphinx.
                -n, --new            Create a new external project or internal task from template.
                -c, --conda [NAME]   Create the conda environment for Isaac Lab. Default name is 'env_isaaclab'.
+               -u, --uv [NAME]      Create the uv environment for Isaac Lab. Default name is 'env_isaaclab'.
 
 Installation
 ~~~~~~~~~~~~

docs/source/setup/quickstart.rst

@@ -29,13 +29,41 @@ pip install route using virtual environments.
 
 To begin, we first define our virtual environment.
 
+.. tab-set::
 
-.. code-block:: bash
+   .. tab-item:: conda
+
+      .. code-block:: bash
+
+         # create a virtual environment named env_isaaclab with python3.11
+         conda create -n env_isaaclab python=3.11
+         # activate the virtual environment
+         conda activate env_isaaclab
+
+   .. tab-item:: uv
+
+      .. tab-set::
+         :sync-group: os
+
+         .. tab-item:: :icon:`fa-brands fa-linux` Linux
+            :sync: linux
+
+            .. code-block:: bash
+
+               # create a virtual environment named env_isaaclab with python3.11
+               uv venv --python 3.11 env_isaaclab
+               # activate the virtual environment
+               source env_isaaclab/bin/activate
+
+         .. tab-item:: :icon:`fa-brands fa-windows` Windows
+            :sync: windows
+
+            .. code-block:: batch
 
-    # create a virtual environment named env_isaaclab with python3.11
-    conda create -n env_isaaclab python=3.11
-    # activate the virtual environment
-    conda activate env_isaaclab
+               # create a virtual environment named env_isaaclab with python3.11
+               uv venv --python 3.11 env_isaaclab
+               # activate the virtual environment
+               env_isaaclab\Scripts\activate
 
 
 Next, install a CUDA-enabled PyTorch 2.7.0 build.