Docker Installation Guide for ROS2 Humble on Windows

The Docker installation path lets you run ROS2 Humble on Windows, macOS, or any Linux distribution without modifying your host operating system. Everything runs inside an isolated container, making it straightforward to start fresh, share environments with teammates, or run multiple ROS2 versions side-by-side. GUI tools such as RViz2 and Gazebo are supported on Windows via X11 forwarding using Xming/Xlaunch.

Prerequisites

Docker Desktop

Install Docker Desktop for your platform (Windows, macOS, or Linux). Ensure the Docker daemon is running before executing any docker commands.

Xlaunch / Xming

Required on Windows for GUI display forwarding. Install Xming and launch Xlaunch before starting the container to enable tools like RViz2 to render their windows on your desktop.

Container Setup

Pull Pre-built Image
Build from Dockerfile

The fastest way to get started is to pull the pre-built ROS2 Humble image published to Docker Hub. Open a terminal (CMD, PowerShell, or bash) and run the following commands.Pull the image:

docker pull xxthanatosxx/ros2-humble:1.0.0

Verify the image was downloaded:

docker images

You should see xxthanatosxx/ros2-humble listed with tag 1.0.0 in the output.Create and start an interactive container:

docker run -it --name ros2-humble-container xxthanatosxx/ros2-humble:1.0.0 /bin/bash

This drops you directly into a bash shell inside the container. The --name flag assigns a memorable name so you can manage the container easily.Start the container again after stopping it:

docker start ros2-humble-container

Stop the running container:

docker stop ros2-humble-container

If you prefer to build your own image — or want to customise the base environment — create a file named Dockerfile with the content below and build it locally.Dockerfile:

#change the distro if needed, you can also use a ubuntu image and make your custom ROS install on it.
FROM ros:humble
ARG DEBIAN_FRONTEND=noninteractive

USER root

RUN apt-get update

RUN apt-get install -y build-essential sudo terminator iproute2 gedit lsb-release lsb-core wget nano

RUN adduser user
RUN adduser user sudo
#remove password
RUN passwd -d user

USER user

The Dockerfile starts from the official ros:humble base image, installs a set of common development tools, and creates a non-root user account with passwordless sudo access for convenience inside the container.Build the image (name it ros2-humble-img):

docker build -t ros2-humble-img .

Create the container with X11 display forwarding:The DISPLAY environment variable points to host.docker.internal:0, which resolves to the Xming server running on your Windows host. The C:\ drive is mounted at /mnt/c so you can access host files from inside the container.

docker run --name ros2-humble --user=user --env=DISPLAY=host.docker.internal:0 --volume="C:\\:/mnt/c" --restart=no --runtime=runc --network=host -t -d ros2-humble-img

Optional — create the container with a dedicated shared folder mount:If you want a specific folder to be synchronised between host and container, add a second --volume flag pointing to your shared directory:

docker run --name ros2-humble --user=user --env=DISPLAY=host.docker.internal:0 --volume="C:\\:/mnt/c" --volume="C:\\Users\\UNIMAR\\Documents\\Docker\\shared_folder:/mnt/shared_folder" --restart=no --runtime=runc --network=host -t -d ros2-humble-img

Inside the container you can then verify the mount with:

cd /mnt/shared_folder

ROS2 Configuration Inside the Container

Once you have a running container (from either tab above), complete the following steps to configure the ROS2 environment and verify the GUI stack.

Source the ROS2 setup file

In the container’s bash shell, source the ROS2 environment for the current session:

source /opt/ros/humble/setup.bash

Persist the source line in .bashrc

Open .bashrc with nano so the environment is loaded automatically in every new shell:

nano .bashrc

Add the following line at the end of the file, then save with Ctrl + O and exit with Ctrl + X:

source /opt/ros/humble/setup.bash

Reload the shell configuration

source ~/.bashrc

Install RViz2

sudo apt-get install ros-humble-rviz2

Reload .bashrc again

After installing new packages it is good practice to reload the environment:

source ~/.bashrc

Launch RViz2

With Xlaunch running on your host, launch RViz2 to confirm that GUI forwarding is working correctly:

rviz2

The RViz2 window should appear on your host desktop, rendered through Xming. If the window does not appear, ensure Xlaunch is running and that the DISPLAY variable inside the container is set to host.docker.internal:0.

File Transfer Between Host and Container

You can copy files and folders in both directions between your Windows host and the running container using docker cp. Copy from host to container:

docker cp "C:\Users\UNIMAR\Documents\Docker\shared_folder" ros2-humble:/home/user/test

Copy from container to host:

docker cp ros2-humble:/ruta/dentro/del/contenedor "C:\Users\UNIMAR\Documents\Docker\local_folder"

The docker cp command works regardless of whether the container is running or stopped, making it a reliable way to extract build artifacts or log files after a session ends.

Get Started

Installation

Configuration

Scripts Reference

Operations

Docker Installation Guide for ROS2 Humble on Windows

Prerequisites

Docker Desktop

Xlaunch / Xming

Container Setup

ROS2 Configuration Inside the Container

File Transfer Between Host and Container

Build docs developers (and LLMs) love

Get Started

Installation

Configuration

Scripts Reference

Operations

Documentation Index

​Prerequisites

Docker Desktop

Xlaunch / Xming

​Container Setup

​ROS2 Configuration Inside the Container

​File Transfer Between Host and Container

Build docs developers (and LLMs) love

Prerequisites

Container Setup

ROS2 Configuration Inside the Container

File Transfer Between Host and Container