Skip to content

K
KincoActuatorIsaacLab
Unverified Commit e4d644f2 authored by Mayank Mittal's avatar Mayank Mittal Committed by GitHub
Browse files
Options

Abstracts out common steps in installation guide (#3445) 

# Description

A lot of content is shared between different installation guides. This
MR moves them to a common "include" so that it is easier for us to
maintain and modify these changes.

## Type of change

- Documentation update

## Checklist

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [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

---------
Co-authored-by: 's avatarKelly Guo <kellyg@nvidia.com>
parent 0d1725e1
Hide whitespace changes
Inline Side-by-side
Showing with 918 additions and 1498 deletions
docs/index.rst
View file @ e4d644f2
......@@ -74,12 +74,13 @@ Table of Contents
=================
.. toctree::
:maxdepth: 2
:maxdepth: 1
:caption: Isaac Lab
source/setup/ecosystem
source/setup/installation/index
source/deployment/index
source/setup/installation/cloud_installation
source/refs/reference_architecture/index
......
docs/source/deployment/index.rst
View file @ e4d644f2
.. _container-deployment:
Container Deployment
====================
......@@ -11,13 +13,65 @@ The Dockerfile is based on the Isaac Sim image provided by NVIDIA, which include
application launcher and the Isaac Sim application. The Dockerfile installs Isaac Lab and its dependencies
on top of this image.
The following guides provide instructions for building the Docker image and running Isaac Lab in a
container.
Cloning the Repository
----------------------
Before building the container, clone the Isaac Lab repository (if not already done):
.. tab-set::
.. tab-item:: SSH
.. code:: bash
git clone git@github.com:isaac-sim/IsaacLab.git
.. tab-item:: HTTPS
.. code:: bash
git clone https://github.com/isaac-sim/IsaacLab.git
Next Steps
----------
After cloning, you can choose the deployment workflow that fits your needs:
- :doc:`docker`
- Learn how to build, configure, and run Isaac Lab in Docker containers.
- Explains the repository's ``docker/`` setup, the ``container.py`` helper script, mounted volumes,
image extensions (like ROS 2), and optional CloudXR streaming support.
- Covers running pre-built Isaac Lab containers from NVIDIA NGC for headless training.
- :doc:`run_docker_example`
- Learn how to run a development workflow inside the Isaac Lab Docker container.
- Demonstrates building the container, entering it, executing a sample Python script (`log_time.py`),
and retrieving logs using mounted volumes.
- Highlights bind-mounted directories for live code editing and explains how to stop or remove the container
while keeping the image and artifacts.
- :doc:`cluster`
- Learn how to run Isaac Lab on high-performance computing (HPC) clusters.
- Explains how to export the Docker image to a Singularity (Apptainer) image, configure cluster-specific parameters,
and submit jobs using common workload managers (SLURM or PBS).
- Includes tested workflows for ETH Zurich's Euler cluster and IIT Genoa's Franklin cluster,
with notes on adapting to other environments.
- :doc:`cloudxr_teleoperation_cluster`
- Deploy CloudXR Teleoperation for Isaac Lab on a Kubernetes cluster.
- Covers system requirements, software dependencies, and preparation steps including RBAC permissions.
- Demonstrates how to install and verify the Helm chart, run the pod, and uninstall it.
.. toctree::
:maxdepth: 1
:maxdepth: 1
:hidden:
docker
cluster
cloudxr_teleoperation_cluster
run_docker_example
docker
run_docker_example
cluster
cloudxr_teleoperation_cluster
docs/source/setup/installation/asset_caching.rst
View file @ e4d644f2
......@@ -34,7 +34,7 @@ Click the message to enable `Hub <https://docs.omniverse.nvidia.com/utilities/la
Hub automatically manages local caching for Isaac Lab assets, so subsequent runs will use cached files instead of
downloading from AWS each time.
.. figure:: ../../_static/setup/asset_caching.jpg
.. figure:: /source/_static/setup/asset_caching.jpg
:align: center
:figwidth: 100%
:alt: Simulator with cache messaging.
......
docs/source/setup/installation/binaries_installation.rst
View file @ e4d644f2
.. _isaaclab-binaries-installation:
Installation using Isaac Sim Binaries
=====================================
Installation using Isaac Sim Pre-built Binaries
===============================================
Isaac Lab requires Isaac Sim. This tutorial installs Isaac Sim first from its binaries, then Isaac Lab from source code.
The following steps first installs Isaac Sim from its pre-built binaries, then Isaac Lab from source code.
Installing Isaac Sim
--------------------
......@@ -11,15 +11,14 @@ Installing Isaac Sim
Downloading pre-built binaries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Please follow the Isaac Sim
`documentation <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_workstation.html>`__
to install the latest Isaac Sim release.
Isaac Sim binaries can be downloaded directly as a zip file from
`here <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/download.html>`__.
If you wish to use the older Isaac Sim 4.5 release, please check the older download page
`here <https://docs.isaacsim.omniverse.nvidia.com/4.5.0/installation/download.html>`__.
From Isaac Sim 4.5 release, Isaac Sim binaries can be `downloaded <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/download.html#download-isaac-sim-short>`_
directly as a zip file.
To check the minimum system requirements, refer to the documentation
`here <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/requirements.html>`__.
Once the zip file is downloaded, you can unzip it to the desired directory.
As an example set of instructions for unzipping the Isaac Sim binaries,
please refer to the `Isaac Sim documentation <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_workstation.html#example-installation>`__.
.. tab-set::
:sync-group: os
......@@ -27,23 +26,12 @@ To check the minimum system requirements, refer to the documentation
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. note::
For details on driver requirements, please see the `Technical Requirements <https://docs.omniverse.nvidia.com/materials-and-rendering/latest/common/technical-requirements.html>`_ guide!
On Linux systems, Isaac Sim directory will be named ``${HOME}/isaacsim``.
On Linux systems, we assume the Isaac Sim directory is named ``${HOME}/isaacsim``.
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. note::
For details on driver requirements, please see the `Technical Requirements <https://docs.omniverse.nvidia.com/materials-and-rendering/latest/common/technical-requirements.html>`_ guide!
From Isaac Sim 4.5 release, Isaac Sim binaries can be downloaded directly as a zip file.
The below steps assume the Isaac Sim folder was unzipped to the ``C:/isaacsim`` directory.
On Windows systems, Isaac Sim directory will be named ``C:/isaacsim``.
On Windows systems, we assume the Isaac Sim directory is named ``C:\isaacsim``.
Verifying the Isaac Sim installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -71,465 +59,22 @@ variables to your terminal for the remaining of the installation instructions:
.. code:: batch
:: Isaac Sim root directory
set ISAACSIM_PATH="C:/isaacsim"
set ISAACSIM_PATH="C:\isaacsim"
:: Isaac Sim python executable
set ISAACSIM_PYTHON_EXE="%ISAACSIM_PATH:"=%\python.bat"
For more information on common paths, please check the Isaac Sim
`documentation <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_faq.html#common-path-locations>`__.
- Check that the simulator runs as expected:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# note: you can pass the argument "--help" to see all arguments possible.
${ISAACSIM_PATH}/isaac-sim.sh
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: note: you can pass the argument "--help" to see all arguments possible.
%ISAACSIM_PATH%\isaac-sim.bat
- Check that the simulator runs from a standalone python script:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# checks that python path is set correctly
${ISAACSIM_PYTHON_EXE} -c "print('Isaac Sim configuration is now complete.')"
# checks that Isaac Sim can be launched from python
${ISAACSIM_PYTHON_EXE} ${ISAACSIM_PATH}/standalone_examples/api/isaacsim.core.api/add_cubes.py
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: checks that python path is set correctly
%ISAACSIM_PYTHON_EXE% -c "print('Isaac Sim configuration is now complete.')"
:: checks that Isaac Sim can be launched from python
%ISAACSIM_PYTHON_EXE% %ISAACSIM_PATH%\standalone_examples\api\isaacsim.core.api\add_cubes.py
.. caution::
If you have been using a previous version of Isaac Sim, you need to run the following command for the *first*
time after installation to remove all the old user data and cached variables:
.. tab-set::
.. tab-item:: :icon:`fa-brands fa-linux` Linux
.. code:: bash
${ISAACSIM_PATH}/isaac-sim.sh --reset-user
.. tab-item:: :icon:`fa-brands fa-windows` Windows
.. code:: batch
%ISAACSIM_PATH%\isaac-sim.bat --reset-user
If the simulator does not run or crashes while following the above
instructions, it means that something is incorrectly configured. To
debug and troubleshoot, please check Isaac Sim
`documentation <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`__
and the
`forums <https://docs.isaacsim.omniverse.nvidia.com/latest/isaac_sim_forums.html>`__.
.. include:: include/bin_verify_isaacsim.rst
Installing Isaac Lab
--------------------
Cloning Isaac Lab
~~~~~~~~~~~~~~~~~
.. note::
We recommend making a `fork <https://github.com/isaac-sim/IsaacLab/fork>`_ of the Isaac Lab repository to contribute
to the project but this is not mandatory to use the framework. If you
make a fork, please replace ``isaac-sim`` with your username
in the following instructions.
Clone the Isaac Lab repository into your workspace:
.. tab-set::
.. tab-item:: SSH
.. code:: bash
git clone git@github.com:isaac-sim/IsaacLab.git
.. tab-item:: HTTPS
.. code:: bash
git clone https://github.com/isaac-sim/IsaacLab.git
.. note::
We provide a helper executable `isaaclab.sh <https://github.com/isaac-sim/IsaacLab/blob/main/isaaclab.sh>`_ that provides
utilities to manage extensions:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: text
./isaaclab.sh --help
usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl-games, rsl-rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-o, --docker Run the docker container helper script (docker/container.sh).
-v, --vscode Generate the VSCode settings file from template.
-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
.. code:: text
isaaclab.bat --help
usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl-games, rsl-rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.bat) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-v, --vscode Generate the VSCode settings file from template.
-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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set up a symbolic link between the installed Isaac Sim root folder
and ``_isaac_sim`` in the Isaac Lab directory. This makes it convenient
to index the python modules and look for extensions shipped with Isaac Sim.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# enter the cloned repository
cd IsaacLab
# create a symbolic link
ln -s path_to_isaac_sim _isaac_sim
# For example: ln -s ${HOME}/isaacsim _isaac_sim
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: enter the cloned repository
cd IsaacLab
:: create a symbolic link - requires launching Command Prompt with Administrator access
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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. attention::
This step is optional. If you are using the bundled python with Isaac Sim, you can skip this step.
.. note::
If you use Conda, we recommend using `Miniconda <https://docs.anaconda.com/miniconda/miniconda-other-installer-links/>`_.
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>`__.
.. include:: include/src_clone_isaaclab.rst
To install ``conda``, please follow the instructions `here <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`__.
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 conda environment is 'env_isaaclab'
./isaaclab.sh --conda # or "./isaaclab.sh -c"
# Option 2: Custom name for conda environment
./isaaclab.sh --conda my_env # or "./isaaclab.sh -c my_env"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: Option 1: Default name for conda environment is 'env_isaaclab'
isaaclab.bat --conda :: or "isaaclab.bat -c"
:: Option 2: Custom name for conda environment
isaaclab.bat --conda my_env :: or "isaaclab.bat -c my_env"
Once created, be sure to activate the environment before proceeding!
.. code:: bash
conda activate env_isaaclab # or "conda activate my_env"
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.
Installation
~~~~~~~~~~~~
- Install dependencies using ``apt`` (on Linux only):
.. code:: bash
# these dependency are needed by robomimic which is not available on Windows
sudo apt install cmake build-essential
- Run the install command that iterates over all the extensions in ``source`` directory and installs them
using pip (with ``--editable`` flag):
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install # or "./isaaclab.sh -i"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat --install :: or "isaaclab.bat -i"
.. note::
By default, the above will install all the learning frameworks. If you want to install only a specific framework, you can
pass the name of the framework as an argument. For example, to install only the ``rl_games`` framework, you can run
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install rl_games # or "./isaaclab.sh -i rl_games"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat --install rl_games :: or "isaaclab.bat -i rl_games"
The valid options are ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``, ``none``.
Verifying the Isaac Lab installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To verify that the installation was successful, run the following command from the
top of the repository:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# Option 1: Using the isaaclab.sh executable
# note: this works for both the bundled python and the virtual environment
./isaaclab.sh -p scripts/tutorials/00_sim/create_empty.py
# Option 2: Using python in your virtual environment
python scripts/tutorials/00_sim/create_empty.py
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: Option 1: Using the isaaclab.bat executable
:: note: this works for both the bundled python and the virtual environment
isaaclab.bat -p scripts\tutorials\00_sim\create_empty.py
:: Option 2: Using python in your virtual environment
python scripts\tutorials\00_sim\create_empty.py
The above command should launch the simulator and display a window with a black
viewport. You can exit the script by pressing ``Ctrl+C`` on your terminal.
On Windows machines, please terminate the process from Command Prompt using
``Ctrl+Break`` or ``Ctrl+fn+B``.
.. figure:: ../../_static/setup/verify_install.jpg
:align: center
:figwidth: 100%
:alt: Simulator with a black window.
If you see this, then the installation was successful! |:tada:|
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!
~~~~~~~~~~~~~~
You can now use Isaac Lab to train a robot through Reinforcement Learning! The quickest way to use Isaac Lab is through the predefined workflows using one of our **Batteries-included** robot tasks. Execute the following command to quickly train an ant to walk!
We recommend adding ``--headless`` for faster training.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
... Or a robot dog!
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
.. include:: include/src_symlink_isaacsim.rst
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
.. include:: include/src_python_virtual_env.rst
Isaac Lab provides the tools you'll need to create your own **Tasks** and **Workflows** for whatever your project needs may be. Take a look at our :ref:`how-to` guides like `Adding your own learning Library <source/how-to/add_own_library>`_ or `Wrapping Environments <source/how-to/wrap_rl_env>`_ for details.
.. include:: include/src_build_isaaclab.rst
.. figure:: ../../_static/setup/isaac_ants_example.jpg
:align: center
:figwidth: 100%
:alt: Idle hands...
.. include:: include/src_verify_isaaclab.rst
docs/source/setup/installation/cloud_installation.rst
View file @ e4d644f2
Running Isaac Lab in the Cloud
==============================
Cloud Deployment
================
Isaac Lab can be run in various cloud infrastructures with the use of `Isaac Automator <https://github.com/isaac-sim/IsaacAutomator>`__.
Isaac Automator allows for quick deployment of Isaac Sim and Isaac Lab onto the public clouds (AWS, GCP, Azure, and Alibaba Cloud are currently supported).
Isaac Lab can be run in various cloud infrastructures with the use of
`Isaac Automator <https://github.com/isaac-sim/IsaacAutomator>`__.
The result is a fully configured remote desktop cloud workstation, which can be used for development and testing of Isaac Lab within minutes and on a budget. Isaac Automator supports variety of GPU instances and stop-start functionality to save on cloud costs and a variety of tools to aid the workflow (like uploading and downloading data, autorun, deployment management, etc).
Isaac Automator allows for quick deployment of Isaac Sim and Isaac Lab onto
the public clouds (AWS, GCP, Azure, and Alibaba Cloud are currently supported).
The result is a fully configured remote desktop cloud workstation, which can
be used for development and testing of Isaac Lab within minutes and on a budget.
Isaac Automator supports variety of GPU instances and stop-start functionality
to save on cloud costs and a variety of tools to aid the workflow
(such as uploading and downloading data, autorun, deployment management, etc).
System Requirements
-------------------
Isaac Automator requires having ``docker`` pre-installed on the system.
* To install Docker, please follow the instructions for your operating system on the
`Docker website`_. A minimum version of 26.0.0 for Docker Engine and 2.25.0 for Docker
compose are required to work with Isaac Automator.
* Follow the post-installation steps for Docker on the `post-installation steps`_ page.
These steps allow you to run Docker without using ``sudo``.
Installing Isaac Automator
--------------------------
For the most update-to-date and complete installation instructions, please refer to `Isaac Automator <https://github.com/isaac-sim/IsaacAutomator?tab=readme-ov-file#installation>`__.
For the most update-to-date and complete installation instructions, please refer to
`Isaac Automator <https://github.com/isaac-sim/IsaacAutomator?tab=readme-ov-file#installation>`__.
To use Isaac Automator, first clone the repo:
.. code-block:: bash
.. tab-set::
git clone https://github.com/isaac-sim/IsaacAutomator.git
.. tab-item:: HTTPS
Isaac Automator requires having ``docker`` pre-installed on the system.
.. code-block:: bash
* To install Docker, please follow the instructions for your operating system on the `Docker website`_. A minimum version of 26.0.0 for Docker Engine and 2.25.0 for Docker compose are required to work with Isaac Automator.
* Follow the post-installation steps for Docker on the `post-installation steps`_ page. These steps allow you to run
Docker without using ``sudo``.
git clone https://github.com/isaac-sim/IsaacAutomator.git
Isaac Automator also requires obtaining a NGC API key.
.. tab-item:: SSH
.. code-block:: bash
git clone git@github.com:isaac-sim/IsaacAutomator.git
Isaac Automator requires obtaining a NGC API key.
* Get access to the `Isaac Sim container`_ by joining the NVIDIA Developer Program credentials.
* Generate your `NGC API key`_ to access locked container images from NVIDIA GPU Cloud (NGC).
......@@ -46,8 +70,8 @@ Isaac Automator also requires obtaining a NGC API key.
Password: <Your NGC API Key>
Running Isaac Automator
-----------------------
Building the container
----------------------
To run Isaac Automator, first build the Isaac Automator container:
......@@ -68,7 +92,14 @@ To run Isaac Automator, first build the Isaac Automator container:
docker build --platform linux/x86_64 -t isa .
Next, enter the automator container:
This will build the Isaac Automator container and tag it as ``isa``.
Running the Automator Commands
------------------------------
First, enter the Automator container:
.. tab-set::
:sync-group: os
......@@ -87,22 +118,54 @@ Next, enter the automator container:
docker run --platform linux/x86_64 -it --rm -v .:/app isa bash
Next, run the deployed script for your preferred cloud:
Next, run the deployment script for your preferred cloud:
.. note::
The ``--isaaclab`` flag is used to specify the version of Isaac Lab to deploy.
The ``v2.2.1`` tag is the latest release of Isaac Lab.
.. tab-set::
:sync-group: cloud
.. tab-item:: AWS
:sync: aws
.. code-block:: bash
./deploy-aws --isaaclab v2.2.1
.. tab-item:: Azure
:sync: azure
.. code-block:: bash
.. code-block:: bash
./deploy-azure --isaaclab v2.2.1
# AWS
./deploy-aws
# Azure
./deploy-azure
# GCP
./deploy-gcp
# Alibaba Cloud
./deploy-alicloud
.. tab-item:: GCP
:sync: gcp
.. code-block:: bash
./deploy-gcp --isaaclab v2.2.1
.. tab-item:: Alibaba Cloud
:sync: alicloud
.. code-block:: bash
./deploy-alicloud --isaaclab v2.2.1
Follow the prompts for entering information regarding the environment setup and credentials.
Once successful, instructions for connecting to the cloud instance will be available in the terminal.
Connections can be made using SSH, noVCN, or NoMachine.
Once successful, instructions for connecting to the cloud instance will be available
in the terminal. The deployed Isaac Sim instances can be accessed via:
- SSH
- noVCN (browser-based VNC client)
- NoMachine (remote desktop client)
Look for the connection instructions at the end of the deployment command output.
Additionally, this info is saved in ``state/<deployment-name>/info.txt`` file.
For details on the credentials and setup required for each cloud, please visit the
`Isaac Automator <https://github.com/isaac-sim/IsaacAutomator?tab=readme-ov-file#deploying-isaac-sim>`__
......@@ -133,16 +196,36 @@ For example:
.. code-block:: batch
./isaaclab.bat -p scripts/reinforcement_learning/rl_games/train.py --task=Isaac-Cartpole-v0
isaaclab.bat -p scripts/reinforcement_learning/rl_games/train.py --task=Isaac-Cartpole-v0
Destroying a Development
-------------------------
Destroying a Deployment
-----------------------
To save costs, deployments can be destroyed when not being used.
This can be done from within the Automator container, which can be entered with command ``./run``.
This can be done from within the Automator container.
Enter the Automator container with the command described in the previous section:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code-block:: bash
./run
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code-block:: batch
docker run --platform linux/x86_64 -it --rm -v .:/app isa bash
To destroy a deployment, run:
To destroy a deployment, run the following command from within the container:
.. code:: bash
......
docs/source/setup/installation/include/bin_verify_isaacsim.rst 0 → 100644
View file @ e4d644f2
Check that the simulator runs as expected:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# note: you can pass the argument "--help" to see all arguments possible.
${ISAACSIM_PATH}/isaac-sim.sh
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: note: you can pass the argument "--help" to see all arguments possible.
%ISAACSIM_PATH%\isaac-sim.bat
Check that the simulator runs from a standalone python script:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# checks that python path is set correctly
${ISAACSIM_PYTHON_EXE} -c "print('Isaac Sim configuration is now complete.')"
# checks that Isaac Sim can be launched from python
${ISAACSIM_PYTHON_EXE} ${ISAACSIM_PATH}/standalone_examples/api/isaacsim.core.api/add_cubes.py
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: checks that python path is set correctly
%ISAACSIM_PYTHON_EXE% -c "print('Isaac Sim configuration is now complete.')"
:: checks that Isaac Sim can be launched from python
%ISAACSIM_PYTHON_EXE% %ISAACSIM_PATH%\standalone_examples\api\isaacsim.core.api\add_cubes.py
.. caution::
If you have been using a previous version of Isaac Sim, you need to run the following command for the *first*
time after installation to remove all the old user data and cached variables:
.. tab-set::
.. tab-item:: :icon:`fa-brands fa-linux` Linux
.. code:: bash
${ISAACSIM_PATH}/isaac-sim.sh --reset-user
.. tab-item:: :icon:`fa-brands fa-windows` Windows
.. code:: batch
%ISAACSIM_PATH%\isaac-sim.bat --reset-user
If the simulator does not run or crashes while following the above
instructions, it means that something is incorrectly configured. To
debug and troubleshoot, please check Isaac Sim
`documentation <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`__
and the
`forums <https://docs.isaacsim.omniverse.nvidia.com/latest/isaac_sim_forums.html>`__.
docs/source/setup/installation/include/pip_python_virtual_env.rst 0 → 100644
View file @ e4d644f2
Preparing a Python Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Creating a dedicated Python environment is **strongly recommended**. It helps:
- **Avoid conflicts with system Python** or other projects installed on your machine.
- **Keep dependencies isolated**, so that package upgrades or experiments in other projects
do not break Isaac Sim.
- **Easily manage multiple environments** for setups with different versions of dependencies.
- **Simplify reproducibility** — the environment contains only the packages needed for the current project,
making it easier to share setups with colleagues or run on different machines.
You can choose different package managers to create a virtual environment.
- **UV**: A modern, fast, and secure package manager for Python.
- **Conda**: A cross-platform, language-agnostic package manager for Python.
- **venv**: The standard library for creating virtual environments in Python.
.. caution::
The Python version of the virtual environment must match the Python version of Isaac Sim.
- For Isaac Sim 5.X, the required Python version is 3.11.
- For Isaac Sim 4.X, the required Python version is 3.10.
Using a different Python version will result in errors when running Isaac Lab.
The following instructions are for Isaac Sim 5.X, which requires Python 3.11.
If you wish to install Isaac Sim 4.5, please use modify the instructions accordingly to use Python 3.10.
- Create a virtual environment using one of the package managers:
.. tab-set::
.. tab-item:: UV Environment
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-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:: Conda Environment
To install conda, please follow the instructions `here <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>__`.
You can create the Isaac Lab environment using the following commands.
We recommend using `Miniconda <https://www.anaconda.com/docs/getting-started/miniconda/main/>`_,
since it is light-weight and resource-efficient environment management system.
.. code-block:: bash
conda create -n env_isaaclab python=3.11
conda activate env_isaaclab
.. tab-item:: venv Environment
To create a virtual environment using the standard library, you can use the
following commands:
.. 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
python3.11 -m venv 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
python3.11 -m venv env_isaaclab
:: activate the virtual environment
env_isaaclab\Scripts\activate
- Ensure the latest pip version is installed. To update pip, run the following command
from inside the virtual environment:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code-block:: bash
pip install --upgrade pip
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code-block:: batch
python -m pip install --upgrade pip
docs/source/setup/installation/include/pip_verify_isaacsim.rst 0 → 100644
View file @ e4d644f2
Verifying the Isaac Sim installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Make sure that your virtual environment is activated (if applicable)
- Check that the simulator runs as expected:
.. code:: bash
# note: you can pass the argument "--help" to see all arguments possible.
isaacsim
- It's also possible to run with a specific experience file, run:
.. code:: bash
# experience files can be absolute path, or relative path searched in isaacsim/apps or omni/apps
isaacsim isaacsim.exp.full.kit
.. note::
When running Isaac Sim for the first time, all dependent extensions will be pulled from the registry.
This process can take upwards of 10 minutes and is required on the first run of each experience file.
Once the extensions are pulled, consecutive runs using the same experience file will use the cached extensions.
.. attention::
The first run will prompt users to accept the Nvidia Omniverse License Agreement.
To accept the EULA, reply ``Yes`` when prompted with the below message:
.. code:: bash
By installing or using Isaac Sim, I agree to the terms of NVIDIA OMNIVERSE LICENSE AGREEMENT (EULA)
in https://docs.isaacsim.omniverse.nvidia.com/latest/common/NVIDIA_Omniverse_License_Agreement.html
Do you accept the EULA? (Yes/No): Yes
If the simulator does not run or crashes while following the above
instructions, it means that something is incorrectly configured. To
debug and troubleshoot, please check Isaac Sim
`documentation <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`__
and the
`forums <https://docs.isaacsim.omniverse.nvidia.com//latest/isaac_sim_forums.html>`__.
docs/source/setup/installation/include/src_build_isaaclab.rst 0 → 100644
View file @ e4d644f2
Installation
~~~~~~~~~~~~
- Install dependencies using ``apt`` (on Linux only):
.. code:: bash
# these dependency are needed by robomimic which is not available on Windows
sudo apt install cmake build-essential
- Run the install command that iterates over all the extensions in ``source`` directory and installs them
using pip (with ``--editable`` flag):
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install # or "./isaaclab.sh -i"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat --install :: or "isaaclab.bat -i"
By default, the above will install **all** the learning frameworks. These include
``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``.
If you want to install only a specific framework, you can pass the name of the framework
as an argument. For example, to install only the ``rl_games`` framework, you can run:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install rl_games # or "./isaaclab.sh -i rl_games"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat --install rl_games :: or "isaaclab.bat -i rl_games"
The valid options are ``all``, ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``,
and ``none``. If ``none`` is passed, then no learning frameworks will be installed.
docs/source/setup/installation/include/src_clone_isaaclab.rst 0 → 100644
View file @ e4d644f2
Cloning Isaac Lab
~~~~~~~~~~~~~~~~~
.. note::
We recommend making a `fork <https://github.com/isaac-sim/IsaacLab/fork>`_ of the Isaac Lab repository to contribute
to the project but this is not mandatory to use the framework. If you
make a fork, please replace ``isaac-sim`` with your username
in the following instructions.
Clone the Isaac Lab repository into your project's workspace:
.. tab-set::
.. tab-item:: SSH
.. code:: bash
git clone git@github.com:isaac-sim/IsaacLab.git
.. tab-item:: HTTPS
.. code:: bash
git clone https://github.com/isaac-sim/IsaacLab.git
We provide a helper executable `isaaclab.sh <https://github.com/isaac-sim/IsaacLab/blob/main/isaaclab.sh>`_
and `isaaclab.bat <https://github.com/isaac-sim/IsaacLab/blob/main/isaaclab.bat>`_ for Linux and Windows
respectively that provides utilities to manage extensions.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: text
./isaaclab.sh --help
usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-o, --docker Run the docker container helper script (docker/container.sh).
-v, --vscode Generate the VSCode settings file from template.
-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
.. code:: text
isaaclab.bat --help
usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.bat) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-v, --vscode Generate the VSCode settings file from template.
-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'.
docs/source/setup/installation/include/src_python_virtual_env.rst 0 → 100644
View file @ e4d644f2
Setting up a Python Environment (optional)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. attention::
This step is optional. If you are using the bundled Python with Isaac Sim, you can skip this step.
Creating a dedicated Python environment for Isaac Lab is **strongly recommended**, even though
it is optional. Using a virtual environment helps:
- **Avoid conflicts with system Python** or other projects installed on your machine.
- **Keep dependencies isolated**, so that package upgrades or experiments in other projects
do not break Isaac Sim.
- **Easily manage multiple environments** for setups with different versions of dependencies.
- **Simplify reproducibility** — the environment contains only the packages needed for the current project,
making it easier to share setups with colleagues or run on different machines.
You can choose different package managers to create a virtual environment.
- **UV**: A modern, fast, and secure package manager for Python.
- **Conda**: A cross-platform, language-agnostic package manager for Python.
Once created, you can use the default Python in the virtual environment (*python* or *python3*)
instead of *./isaaclab.sh -p* or *isaaclab.bat -p*.
.. caution::
The Python version of the virtual environment must match the Python version of Isaac Sim.
- For Isaac Sim 5.X, the required Python version is 3.11.
- For Isaac Sim 4.X, the required Python version is 3.10.
Using a different Python version will result in errors when running Isaac Lab.
.. tab-set::
.. tab-item:: UV Environment
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 environment name 'env_isaaclab'
./isaaclab.sh --uv # or "./isaaclab.sh -u"
# Option 2: Custom name
./isaaclab.sh --uv my_env # or "./isaaclab.sh -u my_env"
.. code:: bash
# Activate environment
source ./env_isaaclab/bin/activate # or "source ./my_env/bin/activate"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. warning::
Windows support for UV is currently unavailable. Please check
`issue #3483 <https://github.com/isaac-sim/IsaacLab/issues/3438>`_ to track progress.
.. tab-item:: Conda Environment
To install conda, please follow the instructions `here <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>__`.
You can create the Isaac Lab environment using the following commands.
We recommend using `Miniconda <https://www.anaconda.com/docs/getting-started/miniconda/main/>`_,
since it is light-weight and resource-efficient environment management system.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# Option 1: Default environment name 'env_isaaclab'
./isaaclab.sh --conda # or "./isaaclab.sh -c"
# Option 2: Custom name
./isaaclab.sh --conda my_env # or "./isaaclab.sh -c my_env"
.. code:: bash
# Activate environment
conda activate env_isaaclab # or "conda activate my_env"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: Option 1: Default environment name 'env_isaaclab'
isaaclab.bat --conda :: or "isaaclab.bat -c"
:: Option 2: Custom name
isaaclab.bat --conda my_env :: or "isaaclab.bat -c my_env"
.. code:: batch
:: Activate environment
conda activate env_isaaclab # or "conda activate my_env"
Once you are in the virtual environment, you do not need to use ``./isaaclab.sh -p`` or
``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`` or ``isaaclab.bat -p`` to run python scripts.
docs/source/setup/installation/include/src_symlink_isaacsim.rst 0 → 100644
View file @ e4d644f2
Creating the Isaac Sim Symbolic Link
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set up a symbolic link between the installed Isaac Sim root folder
and ``_isaac_sim`` in the Isaac Lab directory. This makes it convenient
to index the python modules and look for extensions shipped with Isaac Sim.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# enter the cloned repository
cd IsaacLab
# create a symbolic link
ln -s ${ISAACSIM_PATH} _isaac_sim
# For example:
# Option 1: If pre-built binaries were installed:
# ln -s ${HOME}/isaacsim _isaac_sim
#
# Option 2: If Isaac Sim was built from source:
# ln -s ${HOME}/IsaacSim/_build/linux-x86_64/release _isaac_sim
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: enter the cloned repository
cd IsaacLab
:: create a symbolic link - requires launching Command Prompt with Administrator access
mklink /D _isaac_sim %ISAACSIM_PATH%
:: For example:
:: Option 1: If pre-built binaries were installed:
:: mklink /D _isaac_sim C:\isaacsim
::
:: Option 2: If Isaac Sim was built from source:
:: mklink /D _isaac_sim C:\IsaacSim\_build\windows-x86_64\release
docs/source/setup/installation/include/src_verify_isaaclab.rst 0 → 100644
View file @ e4d644f2
Verifying the Isaac Lab installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To verify that the installation was successful, run the following command from the
top of the repository:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# Option 1: Using the isaaclab.sh executable
# note: this works for both the bundled python and the virtual environment
./isaaclab.sh -p scripts/tutorials/00_sim/create_empty.py
# Option 2: Using python in your virtual environment
python scripts/tutorials/00_sim/create_empty.py
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: Option 1: Using the isaaclab.bat executable
:: note: this works for both the bundled python and the virtual environment
isaaclab.bat -p scripts\tutorials\00_sim\create_empty.py
:: Option 2: Using python in your virtual environment
python scripts\tutorials\00_sim\create_empty.py
The above command should launch the simulator and display a window with a black
viewport. You can exit the script by pressing ``Ctrl+C`` on your terminal.
On Windows machines, please terminate the process from Command Prompt using
``Ctrl+Break`` or ``Ctrl+fn+B``.
.. figure:: /source/_static/setup/verify_install.jpg
:align: center
:figwidth: 100%
:alt: Simulator with a black window.
If you see this, then the installation was successful! |:tada:|
.. note::
If you see an error ``ModuleNotFoundError: No module named 'isaacsim'``, please ensure that the virtual
environment is activated and ``source _isaac_sim/setup_conda_env.sh`` has been executed (for uv as well).
Train a robot!
~~~~~~~~~~~~~~
You can now use Isaac Lab to train a robot through Reinforcement Learning! The quickest way to use Isaac Lab is through the predefined workflows using one of our **Batteries-included** robot tasks. Execute the following command to quickly train an ant to walk!
We recommend adding ``--headless`` for faster training.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
... Or a robot dog!
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
Isaac Lab provides the tools you'll need to create your own **Tasks** and **Workflows** for whatever your project needs may be. Take a look at our :ref:`how-to` guides like `Adding your own learning Library <source/how-to/add_own_library>`_ or `Wrapping Environments <source/how-to/wrap_rl_env>`_ for details.
.. figure:: /source/_static/setup/isaac_ants_example.jpg
:align: center
:figwidth: 100%
:alt: Idle hands...
docs/source/setup/installation/index.rst
View file @ e4d644f2
......@@ -39,12 +39,21 @@ System Requirements
General Requirements
~~~~~~~~~~~~~~~~~~~~
For detailed requirements, please see the
`Isaac Sim system requirements <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/requirements.html>`_.
The basic requirements are:
- **OS:** Ubuntu 22.04 (Linux x64) or Windows 11 (x64)
- **RAM:** 32 GB or more
- **GPU VRAM:** 16 GB or more (additional VRAM may be required for rendering workflows)
- **OS:** Ubuntu 22.04 (Linux x64) or Windows 11 (x64)
For detailed requirements, see the
`Isaac Sim system requirements <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/requirements.html#system-requirements>`_.
**Isaac Sim is built against a specific Python version**, making
it essential to use the same Python version when installing Isaac Lab.
The required Python version is as follows:
- For Isaac Sim 5.X, the required Python version is 3.11.
- For Isaac Sim 4.X, the required Python version is 3.10.
Driver Requirements
~~~~~~~~~~~~~~~~~~~
......@@ -65,6 +74,8 @@ Troubleshooting
Please refer to the `Linux Troubleshooting <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`_
to resolve installation issues in Linux.
You can use `Isaac Sim Compatibility Checker <https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_workstation.html#isaac-sim-compatibility-checker>`_
to automatically check if the above requirements are met for running Isaac Sim on your system.
Quick Start (Recommended)
-------------------------
......@@ -95,7 +106,8 @@ Use this table to decide:
| Pip Only | |:package:| pip install | |:package:| pip install | External extensions only | Special |
| | | | (no training/examples) | case |
+-------------------+------------------------------+------------------------------+---------------------------+------------+
| Docker | |:whale:| Docker | |:floppy_disk:| source (git) | Docker users | Advanced |
+-------------------+------------------------------+------------------------------+---------------------------+------------+
Next Steps
----------
......@@ -125,6 +137,11 @@ Once you've reviewed the installation methods, continue with the guide that matc
- Best for advanced users building **external extensions** with custom runner scripts.
- Note: This does **not** include training or example scripts.
- :ref:`container-deployment`
- Install Isaac Sim and Isaac Lab in a Docker container.
- Best for users who want to use Isaac Lab in a containerized environment.
Asset Caching
-------------
......@@ -142,11 +159,11 @@ Please follow the steps :doc:`asset_caching` to enable asset caching and speed u
.. toctree::
:maxdepth: 2
:hidden:
pip_installation
binaries_installation
source_installation
isaaclab_pip_installation
asset_caching
:maxdepth: 1
:hidden:
pip_installation
binaries_installation
source_installation
isaaclab_pip_installation
asset_caching
docs/source/setup/installation/isaaclab_pip_installation.rst
View file @ e4d644f2
Installing Isaac Lab through Pip
================================
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
......@@ -7,177 +7,50 @@ that are built on top of Isaac Lab. Isaac Lab pip packages **does not** include
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, see :ref:`template-generator`.
To learn about how to set up your own project on top of Isaac Lab, please see :ref:`template-generator`.
.. note::
If you use Conda, we recommend using `Miniconda <https://docs.anaconda.com/miniconda/miniconda-other-installer-links/>`_.
- To use the pip installation approach for Isaac Lab, we recommend first creating a virtual environment.
Ensure that the python version of the virtual environment is **Python 3.11**.
.. tab-set::
.. tab-item:: conda environment
.. code-block:: bash
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::
: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
python3.11 -m venv 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
python3.11 -m venv env_isaaclab
# activate the virtual environment
env_isaaclab\Scripts\activate
- Before installing Isaac Lab, ensure the latest pip version is installed. To update pip, run
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code-block:: bash
pip install --upgrade pip
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
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.
.. code-block:: batch
.. include:: include/pip_python_virtual_env.rst
python -m pip install --upgrade pip
Installing dependencies
~~~~~~~~~~~~~~~~~~~~~~~
.. note::
If you use uv, replace ``pip`` with ``uv pip``.
In case you used UV to create your virtual environment, please replace ``pip`` with ``uv pip``
in the following commands.
- Next, install a CUDA-enabled PyTorch 2.7.0 build for CUDA 12.8.
- Install a CUDA-enabled PyTorch 2.7.0 build for CUDA 12.8:
.. code-block:: bash
.. code-block:: none
pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128
- If you want to use ``rl_games`` for training and inferencing, install the
its Python 3.11 enabled fork:
- If using rl_games for training and inferencing, install the following python 3.11 enabled rl_games fork.
.. code-block:: bash
.. code-block:: none
pip install git+https://github.com/isaac-sim/rl_games.git@python3.11
- Then, install the Isaac Lab packages, this will also install Isaac Sim.
- Install the Isaac Lab packages along with Isaac Sim:
.. code-block:: none
pip install isaaclab[isaacsim,all]==2.2.0 --extra-index-url https://pypi.nvidia.com
.. 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.
Verifying the Isaac Sim installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Make sure that your virtual environment is activated (if applicable)
- Check that the simulator runs as expected:
.. code:: bash
# note: you can pass the argument "--help" to see all arguments possible.
isaacsim
- It's also possible to run with a specific experience file, run:
.. code:: bash
# experience files can be absolute path, or relative path searched in isaacsim/apps or omni/apps
isaacsim isaacsim.exp.full.kit
.. attention::
When running Isaac Sim for the first time, all dependent extensions will be pulled from the registry.
This process can take upwards of 10 minutes and is required on the first run of each experience file.
Once the extensions are pulled, consecutive runs using the same experience file will use the cached extensions.
.. attention::
The first run will prompt users to accept the Nvidia Omniverse License Agreement.
To accept the EULA, reply ``Yes`` when prompted with the below message:
.. code:: bash
By installing or using Isaac Sim, I agree to the terms of NVIDIA OMNIVERSE LICENSE AGREEMENT (EULA)
in https://docs.isaacsim.omniverse.nvidia.com/latest/common/NVIDIA_Omniverse_License_Agreement.html
Do you accept the EULA? (Yes/No): Yes
If the simulator does not run or crashes while following the above
instructions, it means that something is incorrectly configured. To
debug and troubleshoot, please check Isaac Sim
`documentation <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`__
and the
`forums <https://docs.isaacsim.omniverse.nvidia.com//latest/isaac_sim_forums.html>`__.
.. 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.
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
......
docs/source/setup/installation/pip_installation.rst
View file @ e4d644f2
.. _isaaclab-pip-installation:
Installation using Isaac Sim Pip
================================
Installation using Isaac Sim Pip Package
========================================
Isaac Lab requires Isaac Sim. This tutorial first installs Isaac Sim from pip, then Isaac Lab from source code.
Installing Isaac Sim
--------------------
From Isaac Sim 4.0 release, it is possible to install Isaac Sim using pip.
This approach makes it easier to install Isaac Sim without requiring to download the Isaac Sim binaries.
If you encounter any issues, please report them to the
`Isaac Sim Forums <https://docs.isaacsim.omniverse.nvidia.com//latest/common/feedback.html>`_.
The following steps first installs Isaac Sim from pip, then Isaac Lab from source code.
.. attention::
Installing Isaac Sim with pip requires GLIBC 2.35+ version compatibility.
To check the GLIBC version on your system, use command ``ldd --version``.
This may pose compatibility issues with some Linux distributions. For instance, Ubuntu 20.04 LTS has GLIBC 2.31
by default. If you encounter compatibility issues, we recommend following the
This may pose compatibility issues with some Linux distributions. For instance, Ubuntu 20.04 LTS
has GLIBC 2.31 by default. If you encounter compatibility issues, we recommend following the
:ref:`Isaac Sim Binaries Installation <isaaclab-binaries-installation>` approach.
.. attention::
For details on driver requirements, please see the `Technical Requirements <https://docs.omniverse.nvidia.com/materials-and-rendering/latest/common/technical-requirements.html>`_ guide!
On Windows, it may be necessary to `enable long path support <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later>`_ to avoid installation errors due to OS limitations.
.. attention::
.. note::
If you plan to :ref:`Set up Visual Studio Code <setup-vs-code>` later, we recommend following the
:ref:`Isaac Sim Binaries Installation <isaaclab-binaries-installation>` approach.
.. note::
If you use Conda, we recommend using `Miniconda <https://docs.anaconda.com/miniconda/miniconda-other-installer-links/>`_.
- To use the pip installation approach for Isaac Sim, we recommend first creating a virtual environment.
Ensure that the python version of the virtual environment is **Python 3.11**.
.. tab-set::
.. tab-item:: conda environment
.. code-block:: bash
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::
: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
python3.11 -m venv 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
python3.11 -m venv env_isaaclab
# activate the virtual environment
env_isaaclab\Scripts\activate
- Before installing Isaac Sim, ensure the latest pip version is installed. To update pip, run
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
Installing Isaac Sim
--------------------
.. code-block:: bash
From Isaac Sim 4.0 onwards, it is possible to install Isaac Sim using pip.
This approach makes it easier to install Isaac Sim without requiring to download the Isaac Sim binaries.
If you encounter any issues, please report them to the
`Isaac Sim Forums <https://docs.isaacsim.omniverse.nvidia.com/latest/common/feedback.html>`_.
pip install --upgrade pip
.. attention::
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
On Windows, it may be necessary to `enable long path support <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later>`_
to avoid installation errors due to OS limitations.
.. code-block:: batch
.. include:: include/pip_python_virtual_env.rst
python -m pip install --upgrade pip
Installing dependencies
~~~~~~~~~~~~~~~~~~~~~~~
.. note::
If you use uv, replace ``pip`` with ``uv pip``.
In case you used UV to create your virtual environment, please replace ``pip`` with ``uv pip``
in the following commands.
- Next, install a CUDA-enabled PyTorch 2.7.0 build.
- Install a CUDA-enabled PyTorch 2.7.0 build for CUDA 12.8:
.. code-block:: bash
pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128
- Then, install the Isaac Sim packages.
- Install Isaac Sim pip packages:
.. code-block:: none
pip install "isaacsim[all,extscache]==5.0.0" --extra-index-url https://pypi.nvidia.com
Verifying the Isaac Sim installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Make sure that your virtual environment is activated (if applicable)
- Check that the simulator runs as expected:
.. code:: bash
# note: you can pass the argument "--help" to see all arguments possible.
isaacsim
- It's also possible to run with a specific experience file, run:
.. code:: bash
# experience files can be absolute path, or relative path searched in isaacsim/apps or omni/apps
isaacsim isaacsim.exp.full.kit
.. attention::
When running Isaac Sim for the first time, all dependent extensions will be pulled from the registry.
This process can take upwards of 10 minutes and is required on the first run of each experience file.
Once the extensions are pulled, consecutive runs using the same experience file will use the cached extensions.
.. attention::
The first run will prompt users to accept the NVIDIA Software License Agreement.
To accept the EULA, reply ``Yes`` when prompted with the below message:
.. code:: bash
By installing or using Isaac Sim, I agree to the terms of NVIDIA SOFTWARE LICENSE AGREEMENT (EULA)
in https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-software-license-agreement
Do you accept the EULA? (Yes/No): Yes
If the simulator does not run or crashes while following the above
instructions, it means that something is incorrectly configured. To
debug and troubleshoot, please check Isaac Sim
`documentation <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`__
and the
`forums <https://docs.isaacsim.omniverse.nvidia.com//latest/isaac_sim_forums.html>`__.
.. include:: include/pip_verify_isaacsim.rst
Installing Isaac Lab
--------------------
Cloning Isaac Lab
~~~~~~~~~~~~~~~~~
.. note::
We recommend making a `fork <https://github.com/isaac-sim/IsaacLab/fork>`_ of the Isaac Lab repository to contribute
to the project but this is not mandatory to use the framework. If you
make a fork, please replace ``isaac-sim`` with your username
in the following instructions.
Clone the Isaac Lab repository into your workspace:
.. tab-set::
.. tab-item:: SSH
.. code:: bash
git clone git@github.com:isaac-sim/IsaacLab.git
.. tab-item:: HTTPS
.. code:: bash
git clone https://github.com/isaac-sim/IsaacLab.git
.. note::
We provide a helper executable `isaaclab.sh <https://github.com/isaac-sim/IsaacLab/blob/main/isaaclab.sh>`_ that provides
utilities to manage extensions:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: text
./isaaclab.sh --help
usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-o, --docker Run the docker container helper script (docker/container.sh).
-v, --vscode Generate the VSCode settings file from template.
-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
.. code:: text
isaaclab.bat --help
usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.bat) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-v, --vscode Generate the VSCode settings file from template.
-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
~~~~~~~~~~~~
- Install dependencies using ``apt`` (on Ubuntu):
.. code:: bash
sudo apt install cmake build-essential
- Run the install command that iterates over all the extensions in ``source`` directory and installs them
using pip (with ``--editable`` flag):
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install # or "./isaaclab.sh -i"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: bash
isaaclab.bat --install :: or "isaaclab.bat -i"
.. note::
By default, this will install all the learning frameworks. If you want to install only a specific framework, you can
pass the name of the framework as an argument. For example, to install only the ``rl_games`` framework, you can run
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install rl_games # or "./isaaclab.sh -i rl_games"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: bash
isaaclab.bat --install rl_games :: or "isaaclab.bat -i rl_games"
The valid options are ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``, ``none``.
Verifying the Isaac Lab installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To verify that the installation was successful, run the following command from the
top of the repository:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# Option 1: Using the isaaclab.sh executable
# note: this works for both the bundled python and the virtual environment
./isaaclab.sh -p scripts/tutorials/00_sim/create_empty.py
# Option 2: Using python in your virtual environment
python scripts/tutorials/00_sim/create_empty.py
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: Option 1: Using the isaaclab.bat executable
:: note: this works for both the bundled python and the virtual environment
isaaclab.bat -p scripts\tutorials\00_sim\create_empty.py
:: Option 2: Using python in your virtual environment
python scripts\tutorials\00_sim\create_empty.py
The above command should launch the simulator and display a window with a black
viewport as shown below. You can exit the script by pressing ``Ctrl+C`` on your terminal.
On Windows machines, please terminate the process from Command Prompt using
``Ctrl+Break`` or ``Ctrl+fn+B``.
.. figure:: ../../_static/setup/verify_install.jpg
:align: center
:figwidth: 100%
:alt: Simulator with a black window.
If you see this, then the installation was successful! |:tada:|
Train a robot!
~~~~~~~~~~~~~~
You can now use Isaac Lab to train a robot through Reinforcement Learning! The quickest way to use Isaac Lab is through the predefined workflows using one of our **Batteries-included** robot tasks. Execute the following command to quickly train an ant to walk!
We recommend adding ``--headless`` for faster training.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
... Or a robot dog!
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
.. include:: include/src_clone_isaaclab.rst
Isaac Lab provides the tools you'll need to create your own **Tasks** and **Workflows** for whatever your project needs may be. Take a look at our :ref:`how-to` guides like `Adding your own learning Library <source/how-to/add_own_library>`_ or `Wrapping Environments <source/how-to/wrap_rl_env>`_ for details.
.. include:: include/src_build_isaaclab.rst
.. figure:: ../../_static/setup/isaac_ants_example.jpg
:align: center
:figwidth: 100%
:alt: Idle hands...
.. include:: include/src_verify_isaaclab.rst
docs/source/setup/installation/source_installation.rst
View file @ e4d644f2
.. _isaaclab-source-installation:
Installation using Isaac Sim Source
===================================
Installation using Isaac Sim Source Code
========================================
Isaac Lab requires Isaac Sim. This tutorial first installs Isaac Sim from source, then Isaac Lab from source code.
The following steps first installs Isaac Sim from source, then Isaac Lab from source code.
.. note::
......@@ -13,6 +13,9 @@ Isaac Lab requires Isaac Sim. This tutorial first installs Isaac Sim from source
Installing Isaac Sim
--------------------
Building from source
~~~~~~~~~~~~~~~~~~~~
From Isaac Sim 5.0 release, it is possible to build Isaac Sim from its source code.
This approach is meant for users who wish to modify the source code of Isaac Sim as well,
or want to test Isaac Lab with the nightly version of Isaac Sim.
......@@ -62,7 +65,6 @@ for the convenience of users.
Verifying the Isaac Sim installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To avoid the overhead of finding and locating the Isaac Sim installation
directory every time, we recommend exporting the following environment
variables to your terminal for the remaining of the installation instructions:
......@@ -90,452 +92,18 @@ variables to your terminal for the remaining of the installation instructions:
:: Isaac Sim python executable
set ISAACSIM_PYTHON_EXE="%ISAACSIM_PATH:"=%\python.bat"
- Check that the simulator runs as expected:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# note: you can pass the argument "--help" to see all arguments possible.
${ISAACSIM_PATH}/isaac-sim.sh
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: note: you can pass the argument "--help" to see all arguments possible.
%ISAACSIM_PATH%\isaac-sim.bat
- Check that the simulator runs from a standalone python script:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# checks that python path is set correctly
${ISAACSIM_PYTHON_EXE} -c "print('Isaac Sim configuration is now complete.')"
# checks that Isaac Sim can be launched from python
${ISAACSIM_PYTHON_EXE} ${ISAACSIM_PATH}/standalone_examples/api/isaacsim.core.api/add_cubes.py
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: checks that python path is set correctly
%ISAACSIM_PYTHON_EXE% -c "print('Isaac Sim configuration is now complete.')"
:: checks that Isaac Sim can be launched from python
%ISAACSIM_PYTHON_EXE% %ISAACSIM_PATH%\standalone_examples\api\isaacsim.core.api\add_cubes.py
.. caution::
If you have been using a previous version of Isaac Sim, you need to run the following command for the *first*
time after installation to remove all the old user data and cached variables:
.. tab-set::
.. tab-item:: :icon:`fa-brands fa-linux` Linux
.. code:: bash
${ISAACSIM_PATH}/isaac-sim.sh --reset-user
.. tab-item:: :icon:`fa-brands fa-windows` Windows
.. code:: batch
%ISAACSIM_PATH%\isaac-sim.bat --reset-user
If the simulator does not run or crashes while following the above
instructions, it means that something is incorrectly configured. To
debug and troubleshoot, please check Isaac Sim
`documentation <https://docs.omniverse.nvidia.com/dev-guide/latest/linux-troubleshooting.html>`__
and the
`forums <https://docs.isaacsim.omniverse.nvidia.com/latest/isaac_sim_forums.html>`__.
.. include:: include/bin_verify_isaacsim.rst
Installing Isaac Lab
--------------------
Cloning Isaac Lab
~~~~~~~~~~~~~~~~~
.. note::
We recommend making a `fork <https://github.com/isaac-sim/IsaacLab/fork>`_ of the Isaac Lab repository to contribute
to the project but this is not mandatory to use the framework. If you
make a fork, please replace ``isaac-sim`` with your username
in the following instructions.
Clone the Isaac Lab repository into your **workspace**. Please note that the location of the Isaac Lab repository
should be outside of the Isaac Sim repository. For example, if you cloned Isaac Sim into ``~/IsaacSim``,
then you should clone Isaac Lab into ``~/IsaacLab``.
.. tab-set::
.. tab-item:: SSH
.. code:: bash
git clone git@github.com:isaac-sim/IsaacLab.git
.. tab-item:: HTTPS
.. code:: bash
git clone https://github.com/isaac-sim/IsaacLab.git
.. note::
We provide a helper executable `isaaclab.sh <https://github.com/isaac-sim/IsaacLab/blob/main/isaaclab.sh>`_ that provides
utilities to manage extensions:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: text
./isaaclab.sh --help
usage: isaaclab.sh [-h] [-i] [-f] [-p] [-s] [-t] [-o] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.sh) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-o, --docker Run the docker container helper script (docker/container.sh).
-v, --vscode Generate the VSCode settings file from template.
-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
.. code:: text
isaaclab.bat --help
usage: isaaclab.bat [-h] [-i] [-f] [-p] [-s] [-v] [-d] [-n] [-c] -- Utility to manage Isaac Lab.
optional arguments:
-h, --help Display the help content.
-i, --install [LIB] Install the extensions inside Isaac Lab and learning frameworks (rl_games, rsl_rl, sb3, skrl) as extra dependencies. Default is 'all'.
-f, --format Run pre-commit to format the code and check lints.
-p, --python Run the python executable provided by Isaac Sim or virtual environment (if active).
-s, --sim Run the simulator executable (isaac-sim.bat) provided by Isaac Sim.
-t, --test Run all python pytest tests.
-v, --vscode Generate the VSCode settings file from template.
-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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set up a symbolic link between the installed Isaac Sim root folder
and ``_isaac_sim`` in the Isaac Lab directory. This makes it convenient
to index the python modules and look for extensions shipped with Isaac Sim.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# enter the cloned repository
cd IsaacLab
# create a symbolic link
ln -s ${ISAACSIM_PATH} _isaac_sim
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: enter the cloned repository
cd IsaacLab
:: create a symbolic link - requires launching Command Prompt with Administrator access
mklink /D _isaac_sim ${ISAACSIM_PATH}
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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. attention::
This step is optional. If you are using the bundled python with Isaac Sim, you can skip this step.
.. note::
If you use Conda, we recommend using `Miniconda <https://docs.anaconda.com/miniconda/miniconda-other-installer-links/>`_.
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>`__.
.. include:: include/src_clone_isaaclab.rst
To install ``conda``, please follow the instructions `here <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`__.
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 conda environment is 'env_isaaclab'
./isaaclab.sh --conda # or "./isaaclab.sh -c"
# Option 2: Custom name for conda environment
./isaaclab.sh --conda my_env # or "./isaaclab.sh -c my_env"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: Option 1: Default name for conda environment is 'env_isaaclab'
isaaclab.bat --conda :: or "isaaclab.bat -c"
:: Option 2: Custom name for conda environment
isaaclab.bat --conda my_env :: or "isaaclab.bat -c my_env"
Once created, be sure to activate the environment before proceeding!
.. code:: bash
conda activate env_isaaclab # or "conda activate my_env"
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.
Installation
~~~~~~~~~~~~
- Install dependencies using ``apt`` (on Ubuntu):
.. code:: bash
sudo apt install cmake build-essential
- Run the install command that iterates over all the extensions in ``source`` directory and installs them
using pip (with ``--editable`` flag):
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install # or "./isaaclab.sh -i"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: bash
isaaclab.bat --install :: or "isaaclab.bat -i"
.. note::
By default, this will install all the learning frameworks. If you want to install only a specific framework, you can
pass the name of the framework as an argument. For example, to install only the ``rl_games`` framework, you can run
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh --install rl_games # or "./isaaclab.sh -i rl_games"
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: bash
isaaclab.bat --install rl_games :: or "isaaclab.bat -i rl_games"
The valid options are ``rl_games``, ``rsl_rl``, ``sb3``, ``skrl``, ``robomimic``, ``none``.
Verifying the Isaac Lab installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To verify that the installation was successful, run the following command from the
top of the repository:
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
# Option 1: Using the isaaclab.sh executable
# note: this works for both the bundled python and the virtual environment
./isaaclab.sh -p scripts/tutorials/00_sim/create_empty.py
# Option 2: Using python in your virtual environment
python scripts/tutorials/00_sim/create_empty.py
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
:: Option 1: Using the isaaclab.bat executable
:: note: this works for both the bundled python and the virtual environment
isaaclab.bat -p scripts\tutorials\00_sim\create_empty.py
:: Option 2: Using python in your virtual environment
python scripts\tutorials\00_sim\create_empty.py
The above command should launch the simulator and display a window with a black
viewport as shown below. You can exit the script by pressing ``Ctrl+C`` on your terminal.
On Windows machines, please terminate the process from Command Prompt using
``Ctrl+Break`` or ``Ctrl+fn+B``.
.. figure:: ../../_static/setup/verify_install.jpg
:align: center
:figwidth: 100%
:alt: Simulator with a black window.
If you see this, then the installation was successful! |:tada:|
Train a robot!
~~~~~~~~~~~~~~
You can now use Isaac Lab to train a robot through Reinforcement Learning! The quickest way to use Isaac Lab is through the predefined workflows using one of our **Batteries-included** robot tasks. Execute the following command to quickly train an ant to walk!
We recommend adding ``--headless`` for faster training.
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Ant-v0 --headless
... Or a robot dog!
.. tab-set::
:sync-group: os
.. tab-item:: :icon:`fa-brands fa-linux` Linux
:sync: linux
.. code:: bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
.. tab-item:: :icon:`fa-brands fa-windows` Windows
:sync: windows
.. code:: batch
.. include:: include/src_symlink_isaacsim.rst
isaaclab.bat -p scripts/reinforcement_learning/rsl_rl/train.py --task=Isaac-Velocity-Rough-Anymal-C-v0 --headless
.. include:: include/src_python_virtual_env.rst
Isaac Lab provides the tools you'll need to create your own **Tasks** and **Workflows** for whatever your project needs may be. Take a look at our :ref:`how-to` guides like `Adding your own learning Library <source/how-to/add_own_library>`_ or `Wrapping Environments <source/how-to/wrap_rl_env>`_ for details.
.. include:: include/src_build_isaaclab.rst
.. figure:: ../../_static/setup/isaac_ants_example.jpg
:align: center
:figwidth: 100%
:alt: Idle hands...
.. include:: include/src_verify_isaaclab.rst
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment