Installing Isaac ROS on Jetson

This article explains how to set up and install NVIDIA Isaac ROS on Jetson platforms, including Docker configuration, SSD integration, developer environment setup, and compatibility between different JetPack and Isaac ROS versions.

System Requirements

Platform	Hardware	Software	Notes
Jetson	Jetson Orin	JetPack 6.0	ISAAC ROS 3.1
Jetson	Jetson Orin	JetPack 6.1 and 6.2	ISAAC ROS 3.2

Note

For best performance, ensure that power settings are configured appropriately.

Jetson Orin Nano 4GB may not have enough memory to run many of the Isaac ROS packages and is not recommended.

Setup

Hardware Setup

Install Docker from official instructions (here).

Note

ISAAC ROS 3.2 requires Docker Engine 27.2.0 or newer.
ISAAC ROS 3.1 is compatible with Docker Engine 24.0.5.

These numbers refer to the Docker Engine version.
You can check your Docker version by running:

docker --version

SSD Setup (Optional)

Tip

If you are not using an SSD, you can skip this section and go directly to Jetson Platforms Compute Setup.

Physically Install SSD and Auto-Mount

1. Unplug the power and any peripherals from the Jetson developer kit.

2. Physically install an NVMe SSD card on the carrier board of your Jetson developer kit. You must properly seat the connector and secure it with the screw.

3. Reinsert the power cable and any peripherals, and power on the Jetson developer kit.

4. Run lsblk to find the device name.
   

   lsblk
   

   Typical output looks like the following:

   NAME         MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
   loop0          7:0    0    16M  1 loop
   mmcblk1      179:0    0  59.5G  0 disk
   ├─mmcblk1p1  179:1    0    58G  0 part /
   ├─mmcblk1p2  179:2    0   128M  0 part
   ├─mmcblk1p3  179:3    0   768K  0 part
   ├─mmcblk1p4  179:4    0  31.6M  0 part
   ├─mmcblk1p5  179:5    0   128M  0 part
   ├─mmcblk1p6  179:6    0   768K  0 part
   ├─mmcblk1p7  179:7    0  31.6M  0 part
   ├─mmcblk1p8  179:8    0    80M  0 part
   ├─mmcblk1p9  179:9    0   512K  0 part
   ├─mmcblk1p10 179:10   0    64M  0 part
   ├─mmcblk1p11 179:11   0    80M  0 part
   ├─mmcblk1p12 179:12   0   512K  0 part
   ├─mmcblk1p13 179:13   0    64M  0 part
   └─mmcblk1p14 179:14   0 879.5M  0 part
   zram0        251:0    0   1.8G  0 disk [SWAP]
   zram1        251:1    0   1.8G  0 disk [SWAP]
   zram2        251:2    0   1.8G  0 disk [SWAP]
   zram3        251:3    0   1.8G  0 disk [SWAP]
   nvme0n1      259:0    0 238.5G  0 disk
   

   Identify the device corresponding to your SSD. In this example, it is nvme0n1.

5. Format the SSD, create a mount point, and mount it to the filesystem.

   sudo mkfs.ext4 /dev/nvme0n1
   

   sudo mkdir -p /mnt/nova_ssd
   

   sudo mount /dev/nvme0n1 /mnt/nova_ssd
   

6. To ensure that the mount persists after boot, add an entry to the fstab file:

   Identify the UUID for your SSD:

   lsblk -f
   

   Add a new entry to the fstab file:

   sudo vi /etc/fstab
   

   Insert the following line, replacing the UUID with the value found from lsblk -f:

   UUID=************-****-****-****-******** /mnt/nova_ssd/ ext4 defaults 0 2
   

7. Change the ownership of the /mnt/nova_ssd directory.

   sudo chown ${USER}:${USER} /mnt/nova_ssd
   

Migrate Docker directory to SSD

After installing the SSD and making it available to your device, you can use the extra storage capacity to hold the space-heavy Docker directory.

1. Add the nvidia user to the docker group to enable using docker without sudo:

   # Add your user to the docker group
   sudo usermod -aG docker $USER
   # Verify that command succeeded
   id $USER | grep docker
   # Log out and log in for the changes to take effect
   newgrp docker
   

2. Stop the Docker service.

   sudo systemctl stop docker
   

3. Move the existing Docker folder.

   sudo du -csh /var/lib/docker/ && \
     sudo mkdir /mnt/nova_ssd/docker && \
     sudo rsync -axPS /var/lib/docker/ /mnt/nova_ssd/docker/ && \
     sudo du -csh  /mnt/nova_ssd/docker/
   

4. Use a text editor (e.g. Vi) to edit /etc/docker/daemon.json

   sudo vi /etc/docker/daemon.json
   

   Insert "data-root" line similar to the following:

   {
       "runtimes": {
           "nvidia": {
               "path": "nvidia-container-runtime",
               "runtimeArgs": []
           }
       },
       "default-runtime": "nvidia",
       "data-root": "/mnt/nova_ssd/docker"
   }
   

5. Rename the old Docker data directory.

   sudo mv /var/lib/docker /var/lib/docker.old
   

6. Restart the Docker daemon.

   sudo systemctl daemon-reload && \
       sudo systemctl restart docker && \
       sudo journalctl -u docker
   

Jetson Platforms Compute Setup

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.

   Note

   • ISAAC ROS 3.1 → Output should include R36 (release), REVISION: 3.0
   • ISAAC ROS 3.2 → Output should include R36 (release), REVISION: 4.0

   cat /etc/nv_tegra_release
   

3. Run the following command to set the GPU and CPU clock to max.

   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.

   Follow the official Docker installation instructions to 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
   

Jetson Setup for VPI (for ISAAC ROS3.2)

The following instructions are for running compute on Jetson device’s PVA accelerator. The steps are required to run on Jetson device outside a docker container.

1. Generate CDI Spec for GPU/PVA:

   Ensure NVIDIA Container Toolkit is installed on the Jetson device. Use the following command to generate the CDI spec:

   sudo nvidia-ctk cdi generate --mode=csv --output=/etc/cdi/nvidia.yaml
   

2. Install pva-allow-2 package:

   # Add Jetson public APT repository
   sudo apt-get update
   sudo apt-get install software-properties-common
   sudo apt-key adv --fetch-key https://repo.download.nvidia.com/jetson/jetson-ota-public.asc
   sudo add-apt-repository 'deb https://repo.download.nvidia.com/jetson/common r36.4 main'
   sudo apt-get update
   sudo apt-get install -y pva-allow-2
   

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 will also automatically give you access to our Isaac Apt Repository.

Note

All Isaac ROS Quickstarts, tutorials, and examples require the Isaac ROS Dev Docker images as a prerequisite.
Working within these containers ensures correct dependencies, simplifies setup, and grants access to the Isaac Apt Repository for both Jetson and x86_64 platforms.

1. Restart Docker:

   sudo systemctl daemon-reload && sudo systemctl restart docker
   

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

   sudo apt-get install git-lfs
   

   git lfs install --skip-repo
   

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

   with SSDwithout 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
   

   mkdir -p  ~/workspaces/isaac_ros-dev/src
   echo "export ISAAC_ROS_WS=${HOME}/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.

4. Add Environment value

   echo "xhost +local:root" >> ~/.bashrc
   echo "export DISPLAY=:0" >> ~/.bashrc
   echo "export ROS_DOMAIN_ID=1" >> ~/.bashrc
   

Quickstart Set Up Development Environment

1. Follow the official Isaac ROS Getting Started guide to set up your development environment.

2. Clone isaac_ros_common under ${ISAAC_ROS_WS}/src.

   ISAAC ROS 3.1ISAAC ROS 3.2

   cd ${ISAAC_ROS_WS}/src && \
   git clone -b release-3.1 https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common.git isaac_ros_common
   

   ISAAC ROS 3.1 is no longer the latest release

   Continuing to use this version may lead to several issues:

   ISAAC ROS 3.1 is no longer the latest release, and continuing to use this version may lead to several issues:

   • Outdated dependencies: Some Python or ROS 2 packages may be deprecated.
   • Missing repositories: Certain apt or pip sources might have changed or been removed.
   • Compatibility issues: Older versions may not fully support Jetson AGX Orin, CUDA, or TensorRT.
   • Security risks: Older software may contain known vulnerabilities without patches.

   Recommendation: - Always use the latest ISAAC ROS version. - Lock dependencies using requirements.txt and avoid automatic updates. - Test compatibility before upgrading. - Backup old versions before making changes.

   If the image builds successfully and has no version issues, record the installed packages with:

   python3 -m pip list > installed_packages.txt
   

   This will help ensure that future builds use the same dependencies.

   If errors occur during the build due to package version updates, check the latest versions on:

   • PyPI (Python Package Index) to see if newer versions are causing compatibility issues.

   If an error occurs because python3 -m pip install installs a newer version that breaks the image build, use a specific version in the corresponding Dockerfile before the failing installation:

   RUN python3 -m pip install <package-name>==<specific-version>
   

   

   dockerfile:

   

   This ensures that the correct dependency version is used to prevent compatibility issues.

   cd ${ISAAC_ROS_WS}/src && \
   git clone -b release-3.2 https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_common.git isaac_ros_common
   

3. (Optional) Install dependencies for any sensors you want to use by following the sensor-specific guides.

   Tip

   We strongly recommend installing all sensor dependencies before starting any quickstarts.
   Some sensor packages require restarting the Isaac ROS Dev container during installation, which may interrupt your development process.

4. First time executing to create a Docker image, Launch the Docker container using the run_dev.sh script:

   cd $ISAAC_ROS_WS && ./src/isaac_ros_common/scripts/run_dev.sh
   

   Docker Container Running Successfully

   The following image shows the expected output after launching the run_dev.sh script for the first time:

   

Build package

Repositories and Packages

To build Isaac ROS from source code, refer to the official list of Isaac ROS repositories and packages for setup instructions, dependencies, and build procedures.

1. (Host machine) Download Quickstart Assets

   Make sure required libraries are installed.

   sudo apt-get install -y curl jq tar
   

   Then, run these commands to download the asset from NGC:

   NGC_ORG="nvidia"
   NGC_TEAM="isaac"
   PACKAGE_NAME="xxxxx"
   NGC_RESOURCE="xxxxx"
   NGC_FILENAME="xxxx.tar.gz"
   MAJOR_VERSION=3
   MINOR_VERSION=x
   

   Note

   The full version of the script used to fetch the latest compatible asset from NGC can be found directly below this section in the official Isaac ROS Nvblox Quickstart.

   The following image shows the script location in the official documentation:

   

2. Clone this repository under ${ISAAC_ROS_WS}/src.

   cd ${ISAAC_ROS_WS}/src
   git clone --recursive -b release-3.x xxxx
   

3. Launch the Docker container using the run_dev.sh script:

   cd $ISAAC_ROS_WS/src/isaac_ros_common && \
   ./scripts/run_dev.sh
   

   Reference Screenshot for Step 2 & 3

   The following image shows both cloning the repo and launching the container, as documented in the "Installation from source" tab:

   

4. (In container) (Optional) Reinstall setuptools_scm if colcon build fails

   In some environments, you may encounter build issues due to incompatible versions of setuptools_scm.

   If colcon build fails with errors related to versioning or SCM detection, run the following command inside the container:

   pip install setuptools_scm==5.0.0
   

5. Build from Source

6. Run Launch File to test example

   Expected Output Preview

   When you run the example launch file, you should see a reconstructed mesh and depth images like below: