Isaac ROS Dev

Isaac ROS Dev is a container-based workflow to enable production robotics by building your ROS workspace in a consistent, reproducible environment and then being able to deploy the resulting build products as a single, hermetic artifact to run on robot.

Development Environment

The Isaac ROS development environment is run within a Docker container on the target platform using the script After you’ve setup your ROS workspace on your machine with your packages, third party packages, and one or many Isaac ROS packages, you can use this script to launch a Docker container that contains all the system libraries and dependencies to build. sets up a development environment containing ROS 2 and key versions of NVIDIA frameworks prepared for both x86_64 and Jetson. This script prepares a Docker image with a supported configuration for the host machine and delivers you into a bash prompt running inside the container. From here, you are ready to execute ROS 2 build/run commands with your host workspace files, which are mounted into the container and available to edit both on the host and in the container. Note: If you run this script again while it is running, it will attach a new shell to the same running container.


For a complete description of arguments for, see here.

Image keys prepares a base Docker image and mounts your target workspace into the running container. The base Docker image itself is assembled by the script which parses a period-delimited string called an image key. The image key specifies an order of matching Dockerfiles to be built as layers in sequence and fed into the next. matches corresponding Dockerfiles to the image key. For example, an image key of first.second.third could match {Dockerfile.first, Dockerfile.second, Dockerfile.third}, where will build the image for Dockerfile.first, then use that image as the base image while building Dockerfile.second, and so on. The file matching looks for the largest subsequence, so first.second.third could also match {Dockerfile.first.second, Dockerfile.third} depending on which files exist in the search paths.


Using this pattern, you can add your own layers on top of the base images provided in Isaac ROS to set up your environment your way, such as installing additional packages to use.

If you write a file with the name .isaac_ros_common-config in your home directory, you can configure the development environment. The following keys configured in .isaac_ros_common-config can let you specify your own image key and paths to your own Dockerfiles for to use.

An example .isaac_ros_common-config file:

CONFIG_DOCKER_SEARCH_DIRS=(../ros_ws/src/isaac_ros_common/docker ../lib/src/gxf/docker)
BASE_DOCKER_REGISTRY_NAMES=("" "some.other/image/name")

For example, if you had the following directory structure:


where Dockerfile.mine is your own custom image layer, using its host directory for the Docker build context:


... steps ...

COPY myfile.txt /myfile.txt

... more steps ...

You could then extend the base image launched as a container by as follows.



This configures the image key to match with mine included and specifies where to look first for Dockerfiles (workspaces/isaac_ros-dev/ros_ws/mystuff)) before checking the default location.

Prebuilt images

As part of the build image preparation when invoking, Dockerfiles will be matched to the target image key. After the Dockerfiles have been determined, will then check the remote Docker registry for an image that matches the hash of the matched Dockerfiles. If one exists, it will pull it down and use that image rather than try to build the image locally. If you do change the contents of any Dockerfiles, you may change the hash and cause to build the Docker images locally again.

NVIDIA provides prebuilt Docker images for standard image key aarch64.ros2_humble and x86_64.ros2_humble` on NVCR (NVIDIA Container Registry) for your convenience. If your local copies of ``Dockerfile.x86_64, Dockerfile.aarch64, and Dockerfile.ros2_humble match the hashed contents of these prebuilt images, will find and download them to build on rather than start from scratch.

For a complete description of arguments for, see here.

The following keys configured in .isaac_ros_common-config let you determine which remote registries will be checked. An example .isaac_ros_common-config file:

CONFIG_DOCKER_SEARCH_DIRS=(../ros_ws/src/isaac_ros_common/docker ../lib/src/gxf/docker)
BASE_DOCKER_REGISTRY_NAMES=("" "some.other/image/name")

Offline dev environment

If you have already built your base image before and you want to not try to rebuild the base image and perform any operations that could require internet connectivity, you can use the -b/--skip_image_build argument to run offline.


After you’ve built your ROS workspace, you will have one of two products: A) Debians built from bloom-generate or B) ROS workspace install/ directory. The script let’s you package these build products into a runnable Docker image to deploy to your robot.


Once you have your built ROS workspace and/or set of Debians to install, the script packages the ROS workspace directory, other directories, tarballs, and/or Debians to install onto a base image. You can also configure a launch file to run by default each time the container is started. The base image can be specified as an image key for your own custom production environment that will be built with There are more options for you to customize how the final build image will be assembled with your build products.

For a complete description of arguments for, see here.

   --base_image_key "aarch64.ros2_humble" \
   --custom_apt_source "deb focal main" \
   --install_debians "mydebian01,libnvvpi3,tensorrt" \
   --include_dir /workspaces/isaac_ros-dev/tests \
   --include_dir /home/admin/scripts:/home/admin/scripts \
   --ros_ws /workspaces/isaac_ros-dev/ros_ws  \
   --launch_package "isaac_ros_image_proc" \
   --launch_file "" \
   --name ""

In this example, a Docker image named will be built by configuring one custom apt sources, installing three Debians packages, and packaging two host directories and a ROS workspace at /workspaces/isaac_ros-dev/ros_ws on top of a base image built using the key aarch64.ros2_humble. Finally, a launch file and its package were configured to run by default when the container is launched. You can then push this image to your remote Docker registry and run the image as follows.

docker run --rm -it --gpus all

This will launch the container and run by default.