.. _isaac-lab-quickstart: Quickstart ========== This page takes you from a fresh checkout to training, replaying, and inspecting your first task. For prerequisites, see :ref:`installation-system-requirements`. Run all commands from the Isaac Lab repository root with ``uv run``. ``uv`` creates and manages the project environment for you. .. _uv-run-training: Install and run your first task ------------------------------- Install `uv `__, clone Isaac Lab, and enter the repository: .. code-block:: bash curl -LsSf https://astral.sh/uv/install.sh | sh git clone https://github.com/isaac-sim/IsaacLab.git cd IsaacLab Train Cartpole with the Newton MJWarp physics backend (its default, selected explicitly here to show the syntax) and open the Newton visualizer: .. code-block:: bash uv run isaaclab train --task Isaac-Cartpole --num_envs 16 --viz newton_gl physics=newton_mjwarp Training outputs, including checkpoints, are saved under ``logs/``. Add ``--help`` to any command to see its available arguments: .. code-block:: bash uv run isaaclab train --help .. The quickstart media is generated by tools/docs/media/generate_quickstart.sh. .. raw:: html

The same train and play workflow applies across classic control, locomotion, and manipulation tasks.

.. hint:: ``uv run`` installs the core dependencies automatically. To use an optional integration, add ``--extra `` before ``isaaclab``. You can enable multiple extras with a comma-separated list. For example: .. code-block:: bash uv run --extra ovphysx isaaclab train --task Isaac-Cartpole physics=ovphysx Extras make optional capabilities available; task selectors choose which capabilities the task uses For example, ``--extra ovphysx`` makes the OV PhysX integration available, while ``physics=ovphysx`` selects it for the task. You can combine extras as needed. The ``--extra all`` shortcut installs the curated ``ov``, ``rl-games``, ``sb3``, ``skrl``, ``rsl-rl``, ``rerun``, and ``viser`` extras. Isaac Sim, standalone importers, and specialized extras such as ``skrl-jax``, ``rlinf``, ``mimic``, ``teleop``, ``tetrahedralization``, ``video``, ``leapp``, and ``torchrl`` are not included; add them explicitly. See :ref:`installation-optional-extras` for the complete list. Choose an RL library -------------------- Pass ``--rl_library`` to ``train`` or ``play`` to choose the RL framework. If you omit it, Isaac Lab uses the default registered for the task. Most core tasks default to ``rsl_rl``, which is included in the standard ``uv run`` environment and is a good starting point for GPU-based training. .. list-table:: :widths: 18 35 47 :header-rows: 1 * - ``rsl_rl`` - Fast GPU training and policy distillation - ``uv run isaaclab train --rl_library rsl_rl ...`` * - ``rl_games`` - PPO, SAC, and A2C workflows - ``uv run --extra rl-games isaaclab train --rl_library rl_games ...`` * - ``skrl`` - Broad algorithm support with PyTorch and JAX - ``--extra skrl`` for PyTorch; ``--extra skrl-jax`` for JAX * - ``sb3`` - Stable-Baselines3 and CPU-oriented experiments - ``uv run --extra sb3 isaaclab train --rl_library sb3 ...`` * - ``rlinf`` - VLA model fine-tuning - ``uv run --extra rlinf isaaclab train --rl_library rlinf ...`` * - ``torchrl`` - PPO with PyTorch-native RL components - ``uv run --extra torchrl isaaclab train --rl_library torchrl ...`` RL libraries differ in their supported algorithms, tasks, and workflows. See :ref:`choose-an-rl-library` for a detailed comparison. The five commands to know ------------------------- All task commands accept ``--task ``. Start by listing the registered tasks. The list shows which RL libraries and ``physics=`` / ``renderer=`` / ``presets=`` selectors each task supports, and runs without Isaac Sim: .. code-block:: bash uv run isaaclab list_envs --show_presets .. list-table:: :widths: 18 42 40 :header-rows: 1 * - Command - Use it to - Example * - ``train`` - Train a policy with an RL library. - ``uv run isaaclab train --task Isaac-Cartpole`` * - ``play`` - Run a trained policy from a checkpoint. - ``uv run isaaclab play --task Isaac-Cartpole --checkpoint latest`` * - ``zero_agent`` - Run a task with zero actions to verify that it launches correctly. - ``uv run isaaclab zero_agent --task Isaac-Cartpole --viz newton_gl`` * - ``random_agent`` - Run a task with random actions for a quick interaction smoke test. - ``uv run isaaclab random_agent --task Isaac-Cartpole --viz newton_gl`` * - ``benchmark`` - Measure environment, training, play, or startup performance. - ``uv run isaaclab benchmark runtime --task Isaac-Cartpole`` All supported RL libraries use ``--checkpoint`` to choose a checkpoint for playback. See :doc:`/source/concepts/reinforcement_learning` for the complete training and playback reference. .. raw:: html

On the same Franka drawer-opening task, zero_agent applies no control, random_agent samples actions, and play runs a trained policy from a checkpoint.

Choose a backend ---------------- Isaac Lab supports multiple physics and rendering backends. Use ``physics=`` to choose the physics implementation. For camera tasks, use ``renderer=`` to choose the renderer. Available backends depend on the task configuration. Use the task's help output to see its supported selectors: .. code-block:: bash uv run isaaclab train --task Isaac-Cartpole --help See :doc:`/source/concepts/backends_and_presets` for selector names and :ref:`isaaclab-installation-root` for the extras required by each runtime. Use ``presets=`` to apply a task-specific configuration preset. For example: .. code-block:: bash uv run isaaclab train --task Isaac-Cartpole-Camera physics=newton_mjwarp renderer=newton_renderer presets=rgb See :doc:`/source/concepts/backends_and_presets` for backend and preset selection, and :doc:`/source/features/hydra` for arbitrary configuration overrides. Visualize a task ---------------- Use ``--viz`` (or ``--visualizer``) to choose one or more visualizers during training or playback. To use multiple visualizers, pass a comma-separated list without spaces, such as ``--viz newton_gl,rerun``. .. list-table:: :widths: 18 58 24 :header-rows: 1 * - Option - Use it to - Required extra * - ``--viz newton_gl`` - Open the Newton visualizer. - None * - ``--viz rerun`` - Stream the task to the Rerun visualizer. - ``rerun`` * - ``--viz viser`` - Open the web-based Viser visualizer, useful for remote connections. - ``viser`` * - ``--viz kit`` - Open the Kit visualizer when it is available in your environment. - ``isaacsim`` * - Omit ``--viz`` or use ``--viz none`` - Run without a visualizer. - None For example, open the same task in both Newton and Rerun: .. code-block:: bash uv run --extra rerun isaaclab random_agent --task Isaac-Cartpole \ physics=newton_mjwarp --viz newton_gl,rerun See :doc:`/source/concepts/visualization` for visualizer setup and configuration. Log training progress --------------------- RSL-RL writes training metrics to TensorBoard by default under ``logs/rsl_rl/``. Open the dashboard from a second terminal: .. code-block:: bash uv run python -m tensorboard.main --logdir logs/rsl_rl Open ``http://localhost:6006`` to compare rewards, episode lengths, and losses across runs. To use Weights & Biases instead, sign in and log a training run to your project: .. code-block:: bash uv run --extra wandb wandb login uv run --extra wandb isaaclab train --rl_library rsl_rl --task Isaac-Cartpole \ --logger wandb --log_project_name isaaclab Logger options vary by RL library. See :ref:`rl-training-logging` for the options supported by each runner. Play a trained policy --------------------- First, train Cartpole to create a checkpoint: .. code-block:: bash uv run isaaclab train --task Isaac-Cartpole Then play the latest checkpoint in the Newton visualizer: .. code-block:: bash uv run isaaclab play --task Isaac-Cartpole --checkpoint latest --viz newton_gl Choose a checkpoint with one of the following options: .. list-table:: :widths: 38 62 :header-rows: 1 * - Option - Loads * - ``--checkpoint `` - A checkpoint file at the specified local path. Some libraries also accept a run directory. * - ``--checkpoint best`` - The library-specific best or final checkpoint. Falls back to ``latest`` if no separate best or final checkpoint was saved. * - ``--checkpoint latest`` - The highest-step checkpoint from the newest compatible run. * - ``--checkpoint pretrained`` - A pretrained checkpoint hosted by Isaac Lab. Available only for supported tasks. Benchmark a task ---------------- ``isaaclab benchmark`` takes a workflow name as its first argument. Start with ``runtime`` to measure environment-step capacity without a policy: .. code-block:: bash uv run isaaclab benchmark runtime --task Isaac-Cartpole .. list-table:: :widths: 36 64 :header-rows: 1 * - Workflow - Measures * - ``runtime`` - Environment-step capacity with random actions (no policy). * - ``startup`` - Launch, import, configuration, scene creation, and first-step latency. * - ``training`` - End-to-end learning throughput. Requires ``--rl_library``. * - ``play`` - Trained-policy rollout throughput. Requires ``--rl_library`` and ``--checkpoint``. * - ``_multigpu`` - Run ``startup``, ``runtime``, or ``training`` across multiple GPUs by adding the suffix ``_multigpu``. For example, ``runtime_multigpu``. See :ref:`developer_tools_benchmarking` for benchmark fundamentals and :ref:`train_multigpu-command` for multi-GPU training and benchmarks. Configure an editor (optional) ------------------------------ To enable import completion and debugging in VS Code or Cursor, generate the machine-local editor configuration from the repository root: .. code-block:: bash uv run isaaclab --editor If you use the ``isaacsim`` extra, include it so the command can discover the Isaac Sim extensions: .. code-block:: bash uv run --extra isaacsim isaaclab --editor VS Code uses Pylance. Cursor users should install basedpyright instead. See :ref:`setup-vs-code` for complete editor and troubleshooting instructions. Next steps ---------- - Browse registered environments and build a command: :doc:`/source/isaaclab/environments` - Learn how backends and presets fit together: :doc:`/source/concepts/backends_and_presets` - Learn how to override task configuration: :doc:`/source/features/hydra` - Find tutorials and task-focused documentation: :doc:`/source/how-to/index` - Read the installation options and troubleshooting guide: :ref:`isaaclab-installation-root`