Inside osrf/docker_images: how the OSRF ROS and Gazebo images are built

Dockerfiles and scaffolding rather than an installable package

osrf/docker_images is a definition repository, not something you install. Its own description calls it a repository to hold definitions of docker images maintained by OSRF, and the README says it hosts Dockerfiles and scaffolding for images in the Official Library and the OSRF Organization on Docker Hub. The layout follows the image names: top-level entries include .ci/, .github/, doc/, docker/, gazebo/, ros/, ros2/ and sros/, alongside README.md, LICENSE and a file named .travis.yml.unused whose name suggests an earlier CI setup that is no longer wired in. The primary language is Dockerfile and the default branch is master. The repository publishes no GitHub releases, so version tracking happens through tags on Docker Hub rather than through release notes here. Nothing in this tree runs on your machine directly. The usable output is the set of images these definitions produce, and the interesting content is in the README's account of how those images are composed.

Official Library images are the ones tagged for production

Two families live in the Official Library namespace on Docker Hub: ROS, covering both ROS 1 and ROS 2, and Gazebo. The README states that these images are tagged for production and general downstream use, and that if you are targeting released versions of the respective projects, these are the recommended ones. Tag naming differs slightly between them. ROS images are tagged by distribution name, meta package and code name for supported OS base images. Gazebo images are tagged by release version, meta package and code name for supported OS base images. Complete tag listings are not kept in this repository; the README points to the Repo Info tree in the docker-library organisation instead. That distinction matters when you automate a pipeline, because pinning an Official Library tag pins a released distribution rather than a moving one.

Rolling Ridley can change its base image without notice

Alongside the fixed distributions, the ROS Official Library repository carries images for the ROS 2 Rolling Ridley distribution. The README describes it as a rolling release providing the latest bleeding edge packages available via apt, and warns that these images will be updated regularly and may jump base image without notice. The same paragraph places Rolling between the official ROS distributions and the nightly images, which frames it as the middle option, fresher than a released distribution but more predictable than a nightly build. The trade-off is concrete and named in the documentation. If CI pulls a Rolling tag, the operating system underneath can change behind a tag name you had assumed was stable, so a green build last week tells you little about the base layer this week.

OSRF overlay images add desktop meta-packages on top of the Official Library

The OSRF Organization profile on Docker Hub hosts images that the README describes as tagged for development and advanced use cases. The osrf/ros repository builds ROS 1 and ROS 2 images FROM the Official Library by including additional meta-packages, for example desktop installations. The stated motivation is practical: if you need extra dependencies that the Official Library images do not provide, these may save build time during continuous integration or local development. The README also points out that they help when display forwarding is needed for GUIs, which the base images do not cover. Because they layer on published Official Library images, the dependency chain is longer and there is more to version. Treat them as development tooling rather than a production base.

The osrf/ros2 testing variant trades convenience for a testing apt source

The osrf/ros2 repository is specific to ROS 2 and, in the README's wording, aimed particularly at development and continuous integration. The README warns that these images may contain experimental features or unstable interfaces for testing the latest ROS 2 branches. One variant is described in enough detail to be worth reading before you depend on it. The testing image closely mimics the Official Library images but sources the testing apt repository, and it keeps a minimal size with no ros-rolling-* packages pre-installed. The purpose line in the README stops mid-word at intended for Continuous Integra, so the project's own description of the intended workflow is incomplete in this file. The variant trades convenience for control: you get an environment close to the official one, but you install what you need yourself.

Gazebo arm builds exist only as commented-out rows

Architecture coverage differs between the image families, and the README shows the gap in a way that is easy to skim past. The ROS Official Library images list amd64, arm32v7 and arm64v8, each with its own multiarch build status badge. The Gazebo Official Library images list only amd64. The arm32v7 and arm64v8 rows for Gazebo are present in the file but wrapped in an HTML comment, so they are inactive rather than failed. The OSRF profile images for ROS list amd64 only as well. The practical consequence is that a machine with an arm64 processor has a documented path to ROS but not to the Gazebo Official Library image, which is a narrower guarantee than a general claim about supported architectures would suggest.

Pulling with an explicit tag is the documented first step

There is no installation script here, and the README does not present one. The documented way to obtain an OSRF image is a pull with an explicit tag, and both ROS repositories state that images must be pulled using an explicit tag:

docker pull osrf/ros:<tag_name>

docker pull osrf/ros2:<tag_name>

The tag list for each lives on Docker Hub rather than in this repository, on the tags pages for osrf/ros and osrf/ros2. The tag is mandatory because these repositories carry many variants, and a floating pull would leave the resolved version undefined. Note what the instructions do not cover: there is no documented step for authenticating against a private registry, no digest-level pinning recipe for reproducibility, and no documented entrypoint or shell behaviour to expect once the container starts. The README treats Docker Hub as the place where that documentation belongs.

The last push was on 2026-10-07 and CI covers three image families

Maintenance signals come from the CI badges and the commit history rather than from releases, because the repository has no GitHub releases. The last push was on 2026-10-07, and the README links three workflows: CI ROS images, CI ROS 2 images and CI Gazebo images. Each runs against master, and per-architecture status is reported separately through multiarch job badges, so a break can be scoped to one architecture and one image family rather than to the whole tree. The Licence file at the root is Apache-2.0, which covers the definitions held here. The published images are separate artefacts on Docker Hub and each carries its own terms, so an organisation that tracks obligations per image has to read the Docker Hub pages directly rather than infer terms from the source tree.

Editorial conclusion

Adopt the Official Library images when you need released ROS or Gazebo distributions on amd64 or arm, and reach for the osrf/ros and osrf/ros2 overlays only in CI or development where the extra meta-packages and the testing apt source justify a longer dependency chain. Do not treat a Rolling Ridley tag as a stable base, since the README states it may change base image without notice, and do not assume the Gazebo image is available on arm, because only amd64 is listed for it. Verify first which tag you will pin, since tag listings live on Docker Hub rather than in this repository, and check the terms of each image directly on Docker Hub because the Apache-2.0 Licence at the root covers the definitions here, not the published artefacts.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. osrf/docker_images on GitHub
4. README