Getting Started

Isaac ROS is a collection of NVIDIA® CUDA®-accelerated computing packages and AI models designed to streamline and expedite the development of advanced AI robotics applications.

NVIDIA Isaac ROS is built on open-source ROS 2. Through Isaac ROS, developers in the ROS community can take advantage of NVIDIA-accelerated libraries and AI models to fast track their AI robot development and deployment workflows.

System Requirements

Supported Platforms

Platform	Hardware	Software	Storage	Notes
Jetson	Jetson Orin	JetPack 6.1 and 6.2	128+ GB NVMe SSD	For best performance, ensure that power settings are configured appropriately.
x86_64	Ampere or higher NVIDIA GPU Architecture with 8 GB RAM or higher. CUDA 12.6+	Ubuntu 22.04+	32+ GB disk space available	N/A

ROS Support

All Isaac ROS packages are designed and tested to be compatible with ROS 2 Humble.

Initialize Compute

x86 Platforms

1. Install the latest NVIDIA GPU Driver using the official instructions.

2. Verify the NVIDIA GPU Driver is installed correctly:

   nvidia-smi
   

   Confirm that all relevant fields satisfy the requirements.

   • Driver Version

   • CUDA Version

   • GPU Memory

Jetson Platforms

Todo

Update this section with the latest instructions for Orin.

1. Install Jetpack including the nvidia-container package.

2. After boot, confirm that you have installed the correct version of Jetpack by running the following command. Confirm that the output has the terms R36 (release), REVISION: 4.0.

   cat /etc/nv_tegra_release
   

3. Run the following command to set the GPU and CPU clock to max. See Maximizing Jetson Performance for more details.

   sudo /usr/bin/jetson_clocks
   

4. Run the following command to set the power to MAX settings. See Power Mode Controls for more details.

   sudo /usr/sbin/nvpmodel -m 0
   

5. Add your user to the docker group.

   sudo usermod -aG docker $USER
   newgrp docker
   

6. Setup Docker.

   From the official Docker install instructions (here), install the docker-buildx-plugin.

   # Add Docker's official GPG key:
   sudo apt-get update
   sudo apt-get install ca-certificates curl gnupg
   sudo install -m 0755 -d /etc/apt/keyrings
   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
   sudo chmod a+r /etc/apt/keyrings/docker.gpg
   
   # Add the repository to Apt sources:
   echo \
   "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
   "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   sudo apt-get update
   
   sudo apt install docker-buildx-plugin
   

7. Consider the following recommendations for a better experience:

   Todo

   Delete/clean up these files

   • Jetson Storage Setup

   • Preempt Setup

   • Jetson VPI

Create a Workspace

x86 Platforms

Create a ROS 2 workspace for experimenting with Isaac ROS:

mkdir -p  ~/workspaces/isaac_ros-dev/src
echo 'export ISAAC_ROS_WS="${ISAAC_ROS_WS:-${HOME}/workspaces/isaac_ros-dev/}"' >> ~/.bashrc
source ~/.bashrc

Jetson Platforms

1. Install the SSD.

   Todo

   Do we still need to provide instructions? Or is there an external source?

2. Create a ROS 2 workspace for experimenting with Isaac ROS:

   mkdir -p  /mnt/nova_ssd/workspaces/isaac_ros-dev/src
   echo 'export ISAAC_ROS_WS="${ISAAC_ROS_WS:-/mnt/nova_ssd/workspaces/isaac_ros-dev/}"' >> ~/.bashrc
   source ~/.bashrc
   

Configure Isaac ROS Apt Repository

The NVIDIA Isaac ROS Apt Repository hosts the following categories of packages for all users:

• Pre-built Isaac ROS packages for currently-supported platforms

• Auxiliary packages to improve developer experience or to support a legacy OS

To configure the Isaac ROS Apt Repository, follow the steps below:

1. Set the locale on your host system to UTF-8:

   locale  # check for UTF-8
   
   sudo apt update && sudo apt install locales
   sudo locale-gen en_US en_US.UTF-8
   sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
   export LANG=en_US.UTF-8
   
   locale  # verify settings
   

2. Install the dependencies:

   sudo apt update && sudo apt install curl gnupg
   sudo apt install software-properties-common
   sudo add-apt-repository universe
   

3. Source the Isaac ROS Apt Repository:

   NVIDIA hosts the Isaac ROS Apt Repository on two CDNs (Content Distribution Networks), one in the United States (.com) and one in China (.cn).

   Select the appropriate CDN based on your location and other considerations.

   NVIDIA Internal: Run these commands to add the internal apt repository:

   sudo apt install curl -y
   k="/usr/share/keyrings/nvidia-isaac-ros.gpg"
   curl -fsSL https://isaac.download.nvidia.com/isaac-ros/repos.key | sudo gpg --dearmor | sudo tee -a $k > /dev/null
   f="/etc/apt/sources.list.d/nvidia-isaac-ros.list" && sudo touch $f
   s="deb [signed-by=$k] https://urm.nvidia.com/artifactory/sw-isaac-staging-debian-local jammy release-3.3"
   grep -qxF "$s" $f || echo "$s" | sudo tee -a $f
   
   pin_content=$'package: *\nPin: origin isaac.download.nvidia.com\nPin-Priority: 400'
   echo "$pin_content" | sudo tee /etc/apt/preferences.d/isaac-ros
   
   sudo apt-get update
   

   US CDN

   k="/usr/share/keyrings/nvidia-isaac-ros.gpg"
   curl -fsSL https://isaac.download.nvidia.com/isaac-ros/repos.key | sudo gpg --dearmor | sudo tee -a $k > /dev/null
   f="/etc/apt/sources.list.d/nvidia-isaac-ros.list" && sudo touch $f
   s="deb [signed-by=$k] https://isaac.download.nvidia.com/isaac-ros/release-3 jammy release-3.3"
   grep -qxF "$s" $f || echo "$s" | sudo tee -a $f
   
   sudo apt-get update
   

   China CDN

   k="/usr/share/keyrings/nvidia-isaac-ros.gpg"
   curl -fsSL https://isaac.download.nvidia.cn/isaac-ros/repos.key | sudo gpg --dearmor | sudo tee -a $k > /dev/null
   f="/etc/apt/sources.list.d/nvidia-isaac-ros.list" && sudo touch $f
   s="deb [signed-by=$k] https://isaac.download.nvidia.cn/isaac-ros/release-3 jammy release-3.3"
   grep -qxF "$s" $f || echo "$s" | sudo tee -a $f
   
   sudo apt-get update
   

Select Environment Isolation Mode

Based on your use case, decide on an appropriate level of isolation between Isaac ROS and your host system:

Tip

Docker is the recommended option for most users.

It provides the highest level of isolation from your host system.

Mode	Debian packages	Python pip packages	Isolation
Docker (recommended)	Installed inside the container (host unaffected)	Installed inside the container (host unaffected)	High (full container isolation)
Bare Metal (no official support)	Manually installed on host via apt	Manually installed on host via pip	None

This selection will inform subsequent steps in the setup process.

Developer Environment Setup

The development flow currently supported by Isaac ROS is to build on your target platform. You can setup ROS 2 Humble in your host machine with the Isaac Apt Repository and setup dependencies with rosdep OR you can use a Docker-based development environment through Isaac ROS Dev.

We strongly recommend that you set up your developer environment with Isaac ROS Dev. This will streamline your development environment setup with the correct versions of dependencies on both Jetson and x86_64 platforms. Working within the Isaac ROS Dev Docker containers automatically gives you access to Isaac Apt Repository.

All Isaac ROS Quickstarts, tutorials, and examples have been designed with the Isaac ROS Dev Docker images as a prerequisite.

For more conceptual information on the Isaac ROS Dev Docker-based development environment and how to customize it for your needs, see Isaac ROS Dev.

Note

Before you begin, verify that you have sufficient storage space available on your device. We recommend at least 30 GB, to account for the size of the container and datasets.

On Jetson platforms, NVMe SSD storage is required for sufficient and fast storage. See Jetson Setup.

For Jetson with VPI, see Jetson for using VPI.

1. Docker configuration:

   On Jetson platformsOn x86_64 platforms

   Follow this instruction to first set your Jetson up with SSD, then come back to this document and resume from Step 2.

2. Restart Docker:

   sudo systemctl daemon-reload && sudo systemctl restart docker
   

3. Install Git LFS to pull down all large files:

   sudo apt-get install git-lfs
   

   git lfs install --skip-repo
   

4. Create a ROS 2 workspace for experimenting with Isaac ROS:

   Jetson with SSDx86_64 and Jetson without SSD

   mkdir -p  /mnt/nova_ssd/workspaces/isaac_ros-dev/src
   echo "export ISAAC_ROS_WS=/mnt/nova_ssd/workspaces/isaac_ros-dev/" >> ~/.bashrc
   source ~/.bashrc
   

   We expect to use the ISAAC_ROS_WS environmental variable to refer to this ROS 2 workspace directory, in the future.

For further concepts around customizing your development environment, see Isaac ROS Dev.

Isaac Apt Repository

NVIDIA Isaac Apt Repository built on our CDN (Content Distribution Network) hosts the following categories of packages for all users.

1. All Isaac ROS packages pre-built for the currently supported platforms.

2. ROS 2 Humble packages for Jetson users running JetPack 5.x

   For those users interested in running third-party, community-contributed ROS packages other than Isaac ROS packages on JetPack 5.x (based on Ubuntu 20.04 Focal), NVIDIA runs an instance of the official ROS Buildfarm to produce ROS 2 Humble packages back-ported for Ubuntu 20.04 Focal.

3. Auxiliary packages to improve developer experience or to support a legacy OS.

Isaac ROS Buildfarm

The Isaac ROS Buildfarm is a fork of the official ROS Buildfarm with several modifications to build nearly all ROS 2 packages for Ubuntu 20.04 Focal and make them available on the Isaac Apt Repository.

Setting up Isaac Apt Repository

The Isaac Apt Repository is already configured in the Isaac ROS Dev Docker containers, but if you want to setup the Isaac Apt Repository as an apt source in a different environment or for the China CDN, perform the following steps:

Set Locale

locale  # check for UTF-8

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

locale  # verify settings

Install Dependencies

sudo apt update && sudo apt install gnupg wget
sudo apt install software-properties-common
sudo add-apt-repository universe

Setup Source

Register the GPG key with apt. Two options are listed below, one for .com (US CDN) and one for .cn (China CDN) - choose whichever you prefer.

Add the repository to your apt sources.

US CDNChina CDN

wget -qO - https://isaac.download.nvidia.com/isaac-ros/repos.key | sudo apt-key add -
grep -qxF "deb https://isaac.download.nvidia.com/isaac-ros/release-3 $(lsb_release -cs) release-3.3" /etc/apt/sources.list || \
echo "deb https://isaac.download.nvidia.com/isaac-ros/release-3 $(lsb_release -cs) release-3.3" | sudo tee -a /etc/apt/sources.list
sudo apt-get update

Next, for all other ROS 2 packages, ensure you have the official ROS apt repository sourced.

sudo apt update && sudo apt install curl -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

This should allow for normal installation of all ROS 2 packages.

Install core ROS 2 Packages

sudo apt update

Per ROS 2 documentation:

Desktop Install (Recommended): ROS, RViz, demos, tutorials.

sudo apt install ros-humble-desktop

and/or

sudo apt install ros-humble-desktop-full

ROS-Base Install (Bare Bones): Communication libraries, message packages, command line tools. No GUI tools.

sudo apt install ros-humble-ros-base

Development tools: Compilers and other tools to build ROS packages

sudo apt install ros-dev-tools

Integrate External Data Sources (Optional)

Many Isaac ROS demos include pre-recorded rosbag data to help you get started as quickly as possible.

Optionally, these demos can also be integrated with external data sources, including cameras and the Isaac Sim simulation platform.

Sensors

Isaac ROS provides setup instructions for specific camera models from the following product lines:

• RealSense

• StereoLabs ZED

Calibrate your cameras depending on your type of camera and the object it is on:

• Monocular Camera

• Stereo Camera on Robot Arm

• Stereo Camera on Mobile Robot

Isaac Sim

Isaac Sim is NVIDIA’s robotics simulation platform powered by Omniverse.

Isaac Sim can be used to run and test the ROS 2 applications. There are two ways we can configure the system:

• Software in the Loop (SIL) refers to a configuration where the software being tested is not running on the target hardware platform. For example, Isaac ROS packages being tested on x86 before deployment on a Jetson device is SIL.

• Hardware in the Loop (HIL) refers to a configuration where the software is being tested on the target hardware platform. For example, Isaac ROS packages being tested on a Jetson device before deployment is HIL.

In both the configurations, Isaac Sim runs on a x86_64 machine providing sensor data and world information.

Isaac Sim 5.0 and Isaac Sim 5.1

1. Install Isaac Sim, choosing the appropriate working environment:

   • Native

   • Docker

   • Cloud

   Note

   This tutorial assumes the Native environment for Isaac Sim.

2. Follow the Running Native ROS instructions to ensure that ROS 2 and the required packages are installed to successfully enable the ROS 2 Bridge in Omniverse Isaac Sim.

3. Follow the instructions to launch Isaac Sim App Selector window and then click Open in Terminal button.

   

4. Using Isaac Sim ROS 2 libraryUsing bare-metal ROS 2 library

   If you don’t have a system level ROS 2 install, follow the steps outlined here under ROS 2 -> Humble.

   Optionally, if ROS_DOMAIN_ID is needed to create a separate logical network, run the following commands.

   export ROS_DOMAIN_ID=<your_domain_id>
   

5. Launch Isaac Sim.

   ./isaac-sim.sh
   

6. Open Isaac ROS Sample scene as shown below.

   First, enable Robotics Examples menu by clicking Window > Examples > Robotics Examples

   

   Then, in the Robotics Examples tab, select ROS2 > Isaac ROS > Sample Scene and click Load Sample Scene

   

7. Continue with the next steps in your specific Isaac ROS package tutorial.

   Note

   Make sure to set the ROS_DOMAIN_ID environment variable (if set earlier) before running the sample application.

Isaac Sim Tutorial Links

Isaac ROS includes a number of tutorials that demonstrate integration with Isaac Sim.

Each of these links takes you to a tutorial that is listed under Repositories and Packages. They are linked here as a reference and to help you find them faster.

Note

These tutorials were last validated with Isaac Sim 5.0 and Isaac Sim 5.1.

• Tutorial for AprilTag Detection with Isaac Sim

• Tutorial for Visual SLAM with Isaac Sim

• Tutorial for Nvblox with Isaac Sim

• Tutorial for DNN Object Detection with Isaac Sim

• Tutorial for SGM Stereo Disparity with Isaac Sim

• Tutorial for DNN Stereo Depth Estimation with Isaac Sim

• Tutorial for Occupancy Grid Localizer with Isaac Sim

• Tutorial for DNN Image Segmentation with Isaac Sim

• Tutorial for Isaac ROS Mission Client

• Tutorial for RT-DETR with Isaac Sim

• Tutorial for FoundationPose with Isaac Sim

• Tutorial for NITROS Bridge with Isaac Sim

• Tutorial for cuMotion MoveIt Plugin with Isaac Sim

• Tutorial for Isaac ROS Manipulation Reference Workflows with Isaac Sim

Run an Isaac ROS Demo

You’re now ready to run an Isaac ROS demo!

Navigating the Isaac ROS Site

• Isaac ROS offers a collection of GitHub Repositories, each focused on a general robotics problem area. Every repository has its own page under the repository index.

• Isaac ROS repositories are further organized into ROS 2 Packages, each focused on a specific solution implementation or use case. Each package has its own page under the repository-level page.

• Most packages contain a Quickstart, which is a self-contained example that allows you to quickly test out the package’s core functionality. Quickstarts are located on each package’s page.

• Additionally, many packages contain more advanced Tutorials that dive deeper into the package’s functionality. When available, tutorials are listed below the Quickstart on each package’s page.

• Package pages also contain Troubleshooting and API sections to help you use Isaac ROS in your own applications.

• Robotics fundamentals, NVIDIA technology, and other Concepts are explained under the concepts index.

Browse the available Isaac ROS Repositories and Packages to find your first quickstart.

Troubleshooting

See the troubleshooting section for help with setting up your development environment.