Quickstart

Quickstart#

This page takes you from a fresh checkout to training, replaying, and inspecting your first task. For prerequisites, see System requirements. Run all commands from the Isaac Lab repository root with uv run. uv creates and manages the project environment for you.

Install and run your first task#

Install uv, clone Isaac Lab, and enter the repository:

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:

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:

uv run isaaclab train --help

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 <name> before isaaclab. You can enable multiple extras with a comma-separated list. For example:

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 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.

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 Choose an RL library for a detailed comparison.

The five commands to know#

All task commands accept --task <task_name>. 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:

uv run isaaclab list_envs --show_presets

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 Reinforcement Learning for the complete training and playback reference.

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=<backend> to choose the physics implementation. For camera tasks, use renderer=<backend> to choose the renderer. Available backends depend on the task configuration. Use the task’s help output to see its supported selectors:

uv run isaaclab train --task Isaac-Cartpole --help

See Backends and Presets for selector names and Installation for the extras required by each runtime.

Use presets=<name> to apply a task-specific configuration preset. For example:

uv run isaaclab train --task Isaac-Cartpole-Camera physics=newton_mjwarp renderer=newton_renderer presets=rgb

See Backends and Presets for backend and preset selection, and Hydra Configuration System 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.

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:

uv run --extra rerun isaaclab random_agent --task Isaac-Cartpole \
   physics=newton_mjwarp --viz newton_gl,rerun

See 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:

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:

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 Log training progress for the options supported by each runner.

Play a trained policy#

First, train Cartpole to create a checkpoint:

uv run isaaclab train --task Isaac-Cartpole

Then play the latest checkpoint in the Newton visualizer:

uv run isaaclab play --task Isaac-Cartpole --checkpoint latest --viz newton_gl

Choose a checkpoint with one of the following options:

Option

Loads

--checkpoint <path>

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:

uv run isaaclab benchmark runtime --task Isaac-Cartpole

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 Benchmarking for benchmark fundamentals and Multi-GPU and Multi-Node Training 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:

uv run isaaclab --editor

If you use the isaacsim extra, include it so the command can discover the Isaac Sim extensions:

uv run --extra isaacsim isaaclab --editor

VS Code uses Pylance. Cursor users should install basedpyright instead. See Editor setup for complete editor and troubleshooting instructions.

Next steps#