Skip to main content

Running Ubuntu with Docker

You can run Ubuntu in a container using Docker, without installing it as a full OS.

warning

Docker is not ideal for hardware-heavy or GUI-dependent robotics tools.

Not recommended for:

  • ROS 2 GUI tools (RViz, rqt, etc.)
  • Gazebo, MuJoCo, or Isaac Sim
  • Direct USB/serial or real-time control
  • NVIDIA GPU rendering without NVIDIA Container Toolkit

Install Docker​

Follow the official Docker installation guide for your OS. Or use these quick steps:

On Ubuntu​

sudo apt update
sudo apt install -y docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
note

You may need to log out and back in to apply group changes.

On Other Linux OS (Distrobox)​

On other distributions of Linux, distrobox allows for the use of Ubuntu through Docker or Podman.

After installing distrobox, run:

xhost +local:root

Then run the following command (you may need to configure credentials to the Github Container Registry).

docker run --env DISPLAY=$DISPLAY \
  --volume /tmp/.X11-unix:/tmp/.X11-unix \
  --network=host \
  -it ghcr.io/enactic/openarm/ros2:latest-humble \
  /bin/bash

On Windows​

Download Docker Desktop: https://www.docker.com/products/docker-desktop

Follow the GUI install instructions

On macOS​

If you are using an Apple Silicon Mac, it may be necessary to enable Rosetta for Docker.

Follow the instructions at github.com/tiryoh/docker-ros2-desktop-vnc.

note

This will not be very performant, but is good enough for simple experiments.

Run a Container​

Supported Ubuntu + ROS 2 Tags

Common Docker tags for ROS 2:

  • osrf/ros:humble (Ubuntu 22.04)
  • osrf/ros:iron (Ubuntu 22.04)
  • osrf/ros:jazzy (Ubuntu 24.04)

Find more at Docker Hub

# Plain Ubuntu without ROS (replace XX.XX with any version)
docker run -it ubuntu:XX.XX
# Ubuntu + ROS 2 base image (replace <ros-distro> with humble, jazzy, etc.)
docker run -it osrf/ros:<ros-distro>

Inside the container, you can install packages as needed.

apt update
apt install -y curl git sudo build-essential

Persistent Containers​

To avoid losing changes, create a named container that persists:

# Ubuntu + ROS 2 base image (replace <ros-distro> with humble, jazzy, etc.)
docker run -it --name my-ubuntu-dev osrf/ros:<ros-distro>

To stop and resume:

docker stop my-ubuntu-dev
docker start -ai my-ubuntu-dev

Optional: Mount a Local Folder​

To access code on your host machine:

# Ubuntu + ROS 2 base image (replace <ros-distro> with humble, jazzy, etc.)
docker run -it -v ~/my-code:/workspace osrf/ros:<ros-distro>

Inside the container:

cd /workspace

Optional: Create a Dockerfile (for repeatable setups)​

Instead of manually installing packages each time:

ARG ROS_DISTRO= <ros-distro>
#(replace <ros-distro> with humble, jazzy, etc.)

FROM osrf/ros:${ROS_DISTRO}

RUN apt update && apt install -y \
    ros-${ROS_DISTRO}-desktop \
    python3-colcon-common-extensions \
    git curl sudo && \
    apt clean

Then build:

#(replace <ros-distro> with humble, jazzy, etc.)
docker build -t my-ubuntu-dev --build-arg ROS_DISTRO= <ros-distro> .
docker run -it my-ubuntu-dev