Nav2 distributed docker containers for active ROS 2 distributions for development and deployment. For a guide for using Docker for development, see our tutorial at docs.nav2.org.

Currently supported distributions:

• Humble
• Jazzy
• Kilted
• Rolling

Each distribution has two images that are generated: bleeding edge based on the status of the Nav2 branch associated with the distribution (nightly) and the latest officially released version (ex 1.2.15).

Each distribution generates three distinct image targets to balance size and utility:

The images can be found in Packages on the right-hand side of the repository or at this link.

To optimize for different robotics workflows, we provide three specialized tiers. You must specify the tier suffix to ensure you are pulling the correct environment for your needs.

# For a specific released version (all tiers follow the same pattern)
docker pull ghcr.io/ros-navigation/nav2_docker:jazzy-1.3.5-devel

# For a specific released version of arm64 (all tiers follow the same pattern)
docker pull ghcr.io/ros-navigation/nav2_docker:jazzy-1.3.5-standard-arm64

# For Nav2 Developers (cloned source included)
docker pull ghcr.io/ros-navigation/nav2_docker:jazzy-nightly-devel

# For Simulation and Testing (Desktop-Full tools included)
docker pull ghcr.io/ros-navigation/nav2_docker:jazzy-nightly-standard

# For Robot Deployment (Headless/Smallest footprint)
docker pull ghcr.io/ros-navigation/nav2_docker:jazzy-nightly-production

# For ARM64 Hardware (core Nav2, no GUI/Gazebo)
docker pull ghcr.io/ros-navigation/nav2_docker:jazzy-nightly-standard-arm64

We provide two primary workflows depending on whether you want to mount your own workspace or work with an isolated container environment:

Use the Standard image if you have a local nav2_ws and want to use the container's pre-installed dependencies and GUI tools (RViz/Gazebo).

sudo docker run -it --net=host --privileged -v .:/root/nav2_ws --volume="${XAUTHORITY}:/root/.Xauthority" --env="DISPLAY=$DISPLAY" -v="/tmp/.gazebo/:/root/.gazebo/" -v /tmp/.X11-unix:/tmp/.X11-unix:rw --shm-size=1000mb ghcr.io/ros-navigation/nav2_docker:jazzy-nightly-standard

This mounts your local workspace into the container. Build artifacts will persist on your host machine so progress is not lost.

Use the Development image if you wish to work fully isolated within the container using the Nav2 source code already cloned in nav2_ws and prepared in the image.

sudo docker run -it --net=host --privileged --volume="${XAUTHORITY}:/root/.Xauthority" --env="DISPLAY=$DISPLAY" -v="/tmp/.gazebo/:/root/.gazebo/" -v /tmp/.X11-unix:/tmp/.X11-unix:rw --shm-size=1000mb ghcr.io/ros-navigation/nav2_docker:jazzy-nightly-devel

Navigate to /root/nav2_ws within the container to find the complete source, build, and install tree ready for modification.

You can build specific image tiers locally by using the --target flag. The project uses separate Dockerfiles for different architectures:

• docker/Dockerfile - x86_64 builds with three tiers (devel, standard, production)
• docker/Dockerfile.arm64 - ARM64 builds optimized for embedded hardware

The x86_64 Dockerfile uses a dual-builder architecture: builder-full compiles all packages (for devel/standard), while builder-production compiles only core navigation packages (for production).

To build a specific version locally from the root of this repository:

# Build the lean Production image (Headless - core navigation only)
sudo docker build -f docker/Dockerfile --target production -t nav2:local-prod .

# Build the full Development image (Includes source code and all packages)
sudo docker build -f docker/Dockerfile --target devel -t nav2:local-devel .

# Build the Standard image (Includes GUI tools/Sim, no source)
sudo docker build -f docker/Dockerfile --target standard -t nav2:local-standard .

# Build the ARM64 standard image (requires buildx)
sudo docker buildx build --platform linux/arm64 -f docker/Dockerfile.arm64 --target standard -t nav2:local-arm64 .

Note: The production image excludes visualization and simulation packages (nav2_rviz_plugins, nav2_bringup, nav2_system_tests, TurtleBot simulation packages) to minimize size. All core navigation functionality (controllers, planners, costmaps, localization, etc.) is included.

You can customize the build process using the --build-arg flag to suit your specific requirements:

• ROS_DISTRO: Specify the ROS 2 distribution (e.g., --build-arg ROS_DISTRO=humble).
• BUILD=false: Use this if you do not want to compile Nav2 (sets up the environment with dependencies only).
• COLCON_BUILD_ARGS="...": Pass custom arguments to the colcon build process (e.g., --build-arg COLCON_BUILD_ARGS="--symlink-install").

If the upstream OSRF images have changed significantly, it is recommended to pull the latest base image before building to ensure you have the latest security patches and core updates:

# Example for Rolling
sudo docker pull osrf/ros:rolling-desktop-full
sudo docker build -f docker/Dockerfile -t nav2:local .

ARM64 images are provided for robot deployment and development on ARM64 hardware (e.g., NVIDIA Jetson, Raspberry Pi 4/5, Apple Silicon). These images are built natively on ARM64 runners and are available for all supported distributions.

Note: osrf/ros:*-desktop-full does not provide ARM64 packages. ARM64 images are therefore built on ros:*-ros-base and exclude GUI and Gazebo simulation tools. All core navigation packages (controllers, planners, costmaps, localization, behavior trees, etc.) are included, but nav2_rviz_plugins, nav2_bringup, simulation packages, and Gazebo-related dependencies are excluded.

From that point on, the instructions above for local development use may be followed.