.. _isaac-lab-quickstart: Quickstart Guide ======================= This guide is written for those who just can't wait to get their hands dirty and will touch on the most common concepts you will encounter as you build your own projects with Isaac Lab! This includes installation, running RL, finding environments, creating new projects, and more! The power of Isaac Lab comes from a few key features that we will very briefly touch on in this guide. 1) **Vectorization**: Reinforcement Learning requires attempting a task many times. Isaac Lab speeds this process along by vectorizing the environment, a process by which training can be run in parallel across many copies of the same environment, thus reducing the amount of time spent on collecting data before the weights of the model can be updated. Most of the codebase is devoted to defining those parts of the environment that need to be touched by this vectorization system 2) **Modular Design**: Isaac Lab is designed to be modular, meaning that you can design your projects to have various components that can be swapped out for different needs. For example, suppose you want to train a policy that supports a specific subset of robots. You could design the environment and task to be robot agnostic by writing a controller interface layer in the form of one of our Manager classes (the ``ActionManager`` in this specific case). Most of the rest of the codebase is devoted to defining those parts of your project that need to be touched by this manager system. To get started, we will first install Isaac Lab and launch a training script. Quick Installation Guide ------------------------- There are many ways to :ref:`install ` Isaac Lab. For a quick start **without Isaac Sim** (Newton backend only), see the :ref:`kitless-installation` section of the installation guide — just clone the repo and run ``./isaaclab.sh -i``. For the full pip-based installation (recommended for most users), we use **uv** as the preferred package manager. To begin, create a virtual environment: .. tab-set:: .. tab-item:: uv (Recommended) .. 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.12 uv venv --python 3.12 --seed 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.12 uv venv --python 3.12 --seed env_isaaclab :: activate the virtual environment env_isaaclab\Scripts\activate .. tab-item:: conda .. code-block:: bash # create a virtual environment named env_isaaclab with python3.12 conda create -n env_isaaclab python=3.12 # activate the virtual environment conda activate env_isaaclab Next, install a CUDA-enabled PyTorch build that matches your system architecture. .. tab-set:: :sync-group: pip-platform .. tab-item:: :icon:`fa-brands fa-linux` Linux (x86_64) :sync: linux-x86_64 .. code-block:: bash uv pip install -U torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128 .. tab-item:: :icon:`fa-brands fa-windows` Windows (x86_64) :sync: windows-x86_64 .. code-block:: bash uv pip install -U torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128 .. tab-item:: :icon:`fa-brands fa-linux` Linux (aarch64) :sync: linux-aarch64 .. code-block:: bash uv pip install -U torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu130 Before we can install Isaac Sim, we need to make sure pip is updated. To update pip, run .. tab-set:: :sync-group: os .. tab-item:: :icon:`fa-brands fa-linux` Linux :sync: linux .. code-block:: bash uv pip install --upgrade pip .. tab-item:: :icon:`fa-brands fa-windows` Windows :sync: windows .. code-block:: batch uv pip install --upgrade pip and now we can install the Isaac Sim packages. .. code-block:: bash uv pip install "isaacsim[all,extscache]==6.0.0" --extra-index-url https://pypi.nvidia.com --index-strategy unsafe-best-match --prerelease=allow Finally, we can install Isaac Lab. To start, clone the repository using the following .. 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 Installation is now as easy as navigating to the repo and then calling the root script with the ``--install`` 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 use "isaaclab.bat -i" Quick Start Using Isaac Launchable ---------------------------------- For users first learning Isaac Lab, without sufficient local compute resources, the `Isaac Launchable `_ project is a quick way to get started without manual installation. Through this project, users can interact with Isaac Sim and Isaac Lab purely from a web browser, with one tab running Visual Studio Code for development and command execution, and another tab providing the streamed user interface for Isaac Sim. This method uses `NVIDIA Brev `_, a platform that offers easily configurable pay-by-the-hour cloud compute. Brev Launchables are preconfigured, optimized compute and software environments. To try now, click the button below. To learn more about how to use this project, or how to create your own Launchable, please see the project repo `here `_. .. image:: https://brev-assets.s3.us-west-1.amazonaws.com/nv-lb-dark.svg :target: https://brev.nvidia.com/launchable/deploy/now?launchableID=env-35JP2ywERLgqtD0b0MIeK1HnF46 :alt: Click here to deploy Launch Training ------------------- The various backends of Isaac Lab are accessed through their corresponding ``train.py`` and ``play.py`` scripts located in the ``scripts/reinforcement_learning`` directory. Invoking these scripts will require a **Task Name** and a corresponding **Entry Point** to the gymnasium API. For example .. code-block:: bash python scripts/reinforcement_learning/skrl/train.py --task=Isaac-Ant-v0 This will train the mujoco ant to "run". You can see the various launch option available to you with the ``--help`` flag. Note specifically the ``--num_envs`` option and the ``--headless`` flag, both of which can be useful when trying to develop and debug a new environment. Options specified at this level automatically overwrite any configuration equivalent that may be defined in the code (so long as those definitions are part of a ``@configclass``, see below). Selecting the Physics Backend ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use the ``presets=`` argument to select the physics backend at runtime: .. code-block:: bash # MJWarp (Newton backend, Kit-less) with Newton visualizer ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \ --task Isaac-Cartpole-Direct-v0 \ --num_envs 4096 \ presets=newton_mjwarp \ --visualizer newton # PhysX (Kit) — requires Isaac Sim installed ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \ --task Isaac-Cartpole-Direct-v0 \ --num_envs 4096 \ presets=physx # MJWarp with a specific visualizer ./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py \ --task Isaac-Cartpole-Direct-v0 \ --num_envs 4096 \ presets=newton_mjwarp \ --visualizer viser Kit-less visualizer options are ``newton``, ``rerun``, and ``viser``. Multiple visualizers can be combined: ``--visualizer newton,rerun``. List Available Environments ----------------------------- Above, ``Isaac-Ant-v0`` is the task name and ``skrl`` is the RL framework being used. The ``Isaac-Ant-v0`` environment has been registered with the `Gymnasium API `_, and you can see how the entry point is defined by calling the ``list_envs.py`` script, which can be found in ``scripts/environments/list_envs.py``. You should see entries like the following .. code-block:: bash $> python scripts/environments/list_envs.py +--------------------------------------------------------------------------------------------------------------------------------------------+ | Available Environments in Isaac Lab +--------+----------------------+--------------------------------------------+---------------------------------------------------------------+ | S. No. | Task Name | Entry Point | Config . . . +--------+----------------------+--------------------------------------------+---------------------------------------------------------------+ | 2 | Isaac-Ant-Direct-v0 | isaaclab_tasks.direct.ant.ant_env:AntEnv | isaaclab_tasks.direct.ant.ant_env:AntEnvCfg +--------+----------------------+--------------------------------------------+---------------------------------------------------------------+ . . . +--------+----------------------+--------------------------------------------+---------------------------------------------------------------+ | 48 | Isaac-Ant-v0 | isaaclab.envs:ManagerBasedRLEnv | isaaclab_tasks.manager_based.classic.ant.ant_env_cfg:AntEnvCfg +--------+----------------------+--------------------------------------------+---------------------------------------------------------------+ Notice that there are two different ``Ant`` tasks, one for a ``Direct`` environment and one for a ``ManagerBased`` environment. These are the :ref:`two primary workflows` that you can use with Isaac Lab out of the box. The Direct workflow will give you the shortest path to a working custom environment for reinforcement learning, but the Manager based workflow will give your project the modularity required for more generalized development. For the purposes of this quickstart guide, we will only focus on the Direct workflow. Generate Your Own Project -------------------------- Getting a new project started with Isaac Lab can seem daunting at first, but this is why we provide the :ref:`template generator`, to rapidly boilerplate a new project via the command line. .. code-block:: bash ./isaaclab.sh --new This will create a new project for you based on the settings you choose * **External vs Internal**: Determines if the project is meant to be built as a part of the isaac lab repository, or if it is meant to be loaded as an external extension. * **Direct vs Manager**: A direct task primarily contains all the implementation details within the environment definition, while a manager based project is meant to use our modular definitions for the different "parts" of an environment. * **Framework**: You can select more than one option here. This determines which RL frameworks you intend to natively use with your project (which specific algorithm implementations you want to use for training). Once created, navigate to the installed project and run .. code-block:: bash uv pip install -e source/ to complete the installation process and register the environment. Within the directories created by the template generator, you will find at least one ``__init__.py`` file with something that looks like the following .. code-block:: python import gymnasium as gym gym.register( id="Template-isaaclabtutorial_env-v0", entry_point=f"{__name__}.isaaclabtutorial_env:IsaaclabtutorialEnv", disable_env_checker=True, kwargs={ "env_cfg_entry_point": f"{__name__}.isaaclabtutorial_env_cfg:IsaaclabtutorialEnvCfg", "skrl_cfg_entry_point": f"{agents.__name__}.skrl_ppo_cfg:PPORunnerCfg", }, ) This is the function that actually registers an environment for future use. Notice that the ``entry_point`` is literally just the python module path to the environment definition. This is why we need to install the project as a package: the module path **is** the entry point for the gymnasium API. Configurations --------------- Regardless of what you are going to be doing with Isaac Lab, you will need to deal with **Configurations**. Configurations can all be identified by the inclusion of the ``@configclass`` decorator above their class definition and the lack of an ``__init__`` function. For example, consider this configuration class for the :ref:`cartpole environment `. .. code-block:: python @configclass class CartpoleEnvCfg(DirectRLEnvCfg): # env decimation = 2 episode_length_s = 5.0 action_scale = 100.0 # [N] action_space = 1 observation_space = 4 state_space = 0 # simulation sim: SimulationCfg = SimulationCfg(dt=1 / 120, render_interval=decimation) # robot robot_cfg: ArticulationCfg = CARTPOLE_CFG.replace(prim_path="/World/envs/env_.*/Robot") cart_dof_name = "slider_to_cart" pole_dof_name = "cart_to_pole" # scene scene: InteractiveSceneCfg = InteractiveSceneCfg(num_envs=4096, env_spacing=4.0, replicate_physics=True) # reset max_cart_pos = 3.0 # the cart is reset if it exceeds that position [m] initial_pole_angle_range = [-0.25, 0.25] # the range in which the pole angle is sampled from on reset [rad] # reward scales rew_scale_alive = 1.0 rew_scale_terminated = -2.0 rew_scale_pole_pos = -1.0 rew_scale_cart_vel = -0.01 rew_scale_pole_vel = -0.005 Notice that the entire class definition is just a list of value fields and other configurations. Configuration classes are necessary for anything that needs to care about being vectorized by the lab during training. If you want to be able to copy an environment thousands of times, and manage the data from each asynchronously, you need to somehow "label" what parts of the scene matter to this copying process (vectorization). This is what the configuration classes accomplish! In this case, the class defines the configuration for the entire training environment! Notice also the ``num_envs`` variable in the ``InteractiveSceneCfg``. This actually gets overwritten by the CLI argument from within the ``train.py`` script. Configurations provide a direct path to any variable in the configuration hierarchy, making it easy to modify anything "configured" by the environment at launch time. Robots ------- Robots are entirely defined as instances of configurations within Isaac Lab. For details on how robot configurations work, including a full example, see the :doc:`/source/how-to/robots` guide. Apps and Sims -------------- Using the simulation with PhysX requires launching the Isaac Sim app to provide simulation context. When using Newton, launching the app is not required. If you are not running a task defined by the standard workflows, then you are responsible for creating the app, managing the context, and stepping the simulation forward through time. This is the "third workflow": a **Standalone** app, which is what we call the scripts for the frameworks, demos, benchmarks, etc... The Standalone workflow gives you total control over *everything* in the app and simulation context. Developing standalone apps is discussed at length in the `Isaac Sim documentation `_ but there are a few points worth touching on that can be incredibly useful. .. code-block:: python import argparse from isaaclab.app import AppLauncher # add argparse arguments parser = argparse.ArgumentParser( description="This script demonstrates adding a custom robot to an Isaac Lab environment." ) parser.add_argument("--num_envs", type=int, default=1, help="Number of environments to spawn.") # append AppLauncher cli args AppLauncher.add_app_launcher_args(parser) # parse the arguments args_cli = parser.parse_args() # launch omniverse app app_launcher = AppLauncher(args_cli) simulation_app = app_launcher.app The ``AppLauncher`` is the entrypoint to any and all Isaac Sim applications, like Isaac Lab! *Many Isaac Lab and Isaac Sim modules cannot be imported until the app is launched!*. This is done on the second to last line of the code above, when the ``AppLauncher`` is constructed. The ``app_launcher.app`` is our interface to the Kit App Framework; the broader interstitial code that binds the simulation to things the extension management system, or the GUI, etc... In the standalone workflow, this interface, often called the ``simulation_app`` is predominantly used to check if the simulation is running, and cleanup after the simulation finishes.