Isaac ROS Common

Overview

The Isaac ROS Common repository contains a number of scripts and Dockerfiles to help streamline development and testing with the Isaac ROS suite.

Docker containers allow you to quickly set up a sensitive set of frameworks and dependencies to ensure a smooth experience with Isaac ROS packages. The Dockerfiles for x86_64 are based on the version 23.10 image from Deep Learning Frameworks Containers. On Jetson platforms, JetPack manages all of these dependencies for you.

Use of Docker images enables CI|CD systems to scale with DevOps work and run automated testing in cloud native platforms on Kubernetes.

For solutions to known issues, see the Troubleshooting section.

Isaac ROS Dev Scripts

run_dev.py

Builds and launches development environment Docker container with host ROS workspace files mounted, or attaches to an existing running container.

Arguments

Arg	Long argument	Default	Description
-b	--use-cached-build-image	False	Uses the cached build image if available. Useful for running offline after base image has been built once already.
-d	--isaac-dir	Auto-detected from script location or ISAAC_DIR environment variable	The location of the host directory to mount into the dev container as /workspaces/isaac_ros-dev
	--env	ros2_humble (from config file)	Environment layers to include in the image. Can be specified multiple times. Platform is automatically prepended. Defaults are read from the config file.
	--build	False	Build the image remotely if it doesn’t exist locally or in registry.
	--build-local	False	Build the image locally if it doesn’t exist.
	--no-cache	False	Do not use Docker layer cache when building.
	--container-name	isaac_ros_dev_container	Name of the Docker container to create or attach to.
	--platform	Auto-detected (x86_64 or aarch64)	Override the platform architecture.
	--verbose	False	Echoes several key commands to the console for debugging.

Docker Arguments File

Additional Docker run arguments can be specified in a .isaac_ros_dev-dockerargs file. The script searches for this file in the following locations (in order):

1. Path specified by DOCKER_ARGS_FILE environment variable

2. .isaac_ros_dev-dockerargs in the current directory

3. ~/.isaac_ros_dev-dockerargs in your home directory

Each line in the file is treated as a separate Docker argument. A default file is provided in the Isaac ROS Common scripts directory with useful mounts.

To add a new argument without overwriting existing ones:

# Check if argument exists, append if not
grep -qxF -- '--pid=host' .isaac_ros_dev-dockerargs 2>/dev/null || echo "--pid=host" >> .isaac_ros_dev-dockerargs

Example file contents:

--pid=host
-v /path/to/data:/data
-e MY_ENV_VAR=value

Config Keys

Values read from ~/.isaac_ros_common-config if it exists.

Key	Type	Examples	Description
cache_from_registry_names	List of string registry names	["nvcr.io/isaac/ros", "nvcr.io/nvidian/isaac-ros/ros"]	Docker image names to search for tags for matching prebuilt images.
image_key_order	List of period-delimited strings	["ros2_humble.realsense"]	Default image key layers to use for building.

build_image_layers.py

Builds a Docker image by parsing an image key (period-delimited string of keys), matching local Dockerfiles corresponding to those keys, and building them in sequence, feeding the result of one as the base image of the next.

This script is called internally by run_dev.py when building images, but can also be run standalone.

Arguments

Arg	Long argument	Default	Description
-i	--image_key	(required)	Image key to resolve. Can be specified multiple times to build multiple layers (for example, -i x86_64 -i ros2_humble).
-b	--build_arg	(none)	Additional build arguments as KEY=VALUE. Can be specified multiple times.
-n	--image_name	(none)	Set final image name for the built image.
-c	--config_file	.build_image_layers.yaml	Config YAML file path for build configuration.
-v	--verbose	False	Enable verbose mode for debugging.
	--no-cache	False	Do not use cached layers for image build.
-p	--platform	Auto-detected from image keys	Target platform architecture (for example, aarch64 or x86_64). Overrides auto-detection.
	--base_image	(none)	Override base image for the first build layer.
	--context_dir	(none)	Override context directory for the final build target. Also added to docker search directories.
	--nvcr	False	Push an NVCR (NVIDIA Container Registry) image tag in addition to the standard tag.
	--skip-registry-check	False	Skip checking remote registry for existing images. Useful for forcing rebuilds.
	--build-local	False	Force local building instead of using remote builder.

Config Keys

Values read from ~/.isaac_ros_common-config (shell format) or .build_image_layers.yaml (YAML format).

Key	Type	Examples	Description
cache_from_registry_names	List of string registry names	["nvcr.io/isaac/ros", "nvcr.io/nvidian/isaac-ros/ros"]	Docker image names to search for tags for matching prebuilt images.
cache_to_registry_names	List of string registry names	["nvcr.io/nvidian/isaac-ros/ros"]	Docker registry names to push built images and cache layers to.
image_key_order	List of period-delimited strings	["ros2_humble.realsense"]	Default image key layers to use for building. Defines ordering priority.
docker_search_dirs	List of directory paths	["docker", "../custom_docker"]	Directories to search for Dockerfiles matching image keys.
remote_builder	Dictionary with platform keys	{"x86_64": "tcp://builder:2375", "aarch64": "ssh://builder"}	Remote Docker builder endpoints by platform for distributed builds.

docker_deploy.sh

Packages prebuilt build artifacts from a ROS workspace and/or set of Debians into a runnable Docker image.

Arguments

Arg	Long argument	Default	Description
-a	--custom_apt_source	(none)	Adds your own apt-get sources so that Debian installations can pull from your Debian repositories.
-b	--base_image_key	${PLATFORM}.ros2_humble	Image key to use as base image before layering on build products.
-d	--include_dir	(none)	Host directory path that will be layered in as a root overlay into the final Docker image. Repeated.
-f	--launch_file	(none)	Launch file name to run by default on container entrypoint. Must be specified with -p.
-i	--install_debians	(none)	Comma-delimited string of Debians to installed with apt-get install on the base image.
-n	--name	isaac_ros_deploy	Name to use for the Docker image being built.
-p	--launch_package	(none)	ROS package name that hosts the target launch file. Must be specified with -f.
-s	--suffix_image_key	(none)	Image key to use as additional layers after the build products have been added.
-t	--include_tarball	(none)	Tarball to be staged as a root overlay on top of the base image. Repeatable.
-w	--ros_ws	(none)	Path to ROS workspace to layer in install/ directory from and add a rosdep install when building Docker image.

Config Keys

Shell values read from ~/.isaac_ros_common-config if exists.

Key	Type	Examples	Description
BASE_IMAGE_KEY	Period-delimited string	release_base_aarch64.ros2_humble	Base image to layer build products on top of.
CUSTOM_APT_SOURCES	Array of string apt sources	("deb https://mycool-apt-get-server.com/ros-debian-local focal main")	Custom apt sources to add for Debian installs.
DEPLOY_IMAGE_NAME	string	myimage	Name of Docker image built.
INSTALL_DEBIANS_CSV	Comma-delimited string	libnvvpi3,tensorrt,ros-humble-isaac-ros-all	List of Debians to install on top of base image.
INCLUDE_DIRS	Array of directory absolute paths	("/workspaces/myfiles" "/some/other/dir")	Host directories to include as a root overlay in final image.
INCLUDE_TARBALLS	Array of directory absolute file paths	("/workspaces/myfiles.tar.gz" "/some/other/files.tar.gz")	Paths to .tar.gz files containing root overlays.
ROS_WS	String path	/workspaces/isaac_ros-dev/ros_ws	Path to ROS workspace with built install/ directory to include.
LAUNCH_PACKAGE	string	isaac_ros_image_pipeline	ROS package name hosting the launch file to run by default in container.
LAUNCH_FILE	string	isaac_ros_image_flip.launch.py	Launch file to run by default in container.

Supported Platforms

This package is designed and tested to be compatible with ROS 2 Humble running on Jetson or an x86_64 system with an NVIDIA GPU.

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

Docker

To simplify development, we strongly recommend leveraging the Isaac ROS Dev Docker images by following these steps. This streamlines your development environment setup with the correct versions of dependencies on both Jetson and x86_64 platforms.

Note

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

Customize your Dev Environment

To customize your development environment, reference this guide.

Updates

Date	Changes
2024-12-10	Refactored Dockerfiles
2024-09-26	Updated for Isaac ROS 3.1
2024-05-30	Update to be compatible with JetPack 6.0
2023-10-18	Updated for Isaac ROS 2.0.0
2023-05-25	Refreshed ROS 2 Humble
2023-04-05	Experimental support for WSL2, merged image keys humble and nav2 into ros2_humble
2022-10-19	Minor updates and bugfixes
2022-08-31	Update to be compatible with JetPack 5.0.2
2022-06-30	Support ROS 2 Humble and miscellaneous bug fixes.
2022-06-16	Update run_dev.sh and removed isaac_ros_nvengine
2021-10-20	Migrated to NVIDIA-ISAAC-ROS, added isaac_ros_nvengine and isaac_ros_nvengine_interfaces packages
2021-08-11	Initial release to NVIDIA-AI-IOT