# ros_gz is the compatibility layer between ROS 2 and Gazebo

> gazebosim/ros_gz is the set of packages that connect the ROS 2 graph to the Gazebo simulator, covering a bidirectional transport bridge, image and point cloud transport, launch files and demos. The real documentation is its version matrix, which maps every ROS 2 distro to the Gazebo release it works with, and which pairings still need a source build.

**gazebosim/ros_gz** — Integration between ROS (1 and 2) and Gazebo simulation

- Repository: https://github.com/gazebosim/ros_gz
- Website: https://gazebosim.org
- Stars: 547 · Forks: 236
- Language: C++
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/gazebosim-ros-gz

## What sits between the ROS 2 graph and the simulator

ros_gz is the integration layer between ROS and the Gazebo simulator, and the repository description is blunt about it, saying only that it is the integration between ROS 1 and 2 and Gazebo simulation. The audience is robotics developers who have decided to simulate in Gazebo and want their ROS 2 nodes, topics and services to talk to it rather than sitting on either side of a gap. The C++ implementation is the practical part. The simulator speaks its own transport, and ROS 2 speaks its own, and something has to translate between the two, including the message types that carry sensor data, clock ticks and simulation control commands. The default branch is ros2, and the ROS 1 compatibility story lives elsewhere, in the noetic branch, whose README is where you should look if you are still on ROS 1. The project is licensed under Apache-2.0 and is developed by the Gazebo simulation organisation itself rather than by a third party, which is the first thing to check for any dependency you intend to build a simulation workflow on.

## Six packages doing six different jobs

The package list in the README is short enough to read as a map of the integration. ros_gz is the metapackage that provides all the other packages, so it is the one to depend on if you want the whole set. ros_gz_bridge is the bidirectional transport bridge between Gazebo Transport and ROS, and it is the piece most projects need first, since it is what allows a message published on a Gazebo topic to appear on a ROS topic and the other way round. ros_gz_image is deliberately narrower, a unidirectional transport bridge for images from Gazebo Transport to ROS using image_transport, which is the right choice when you only need to bring camera data across and want the image pipeline conventions of the ROS ecosystem. ros_gz_sim supplies convenient launch files and executables for using Gazebo Sim with ROS, ros_gz_sim_demos holds demos of the integration, and ros_gz_point_cloud provides plugins for publishing point clouds to ROS from Gazebo Sim simulations. The repository tree also contains ros_gz_interfaces, which holds the message definitions the bridge relies on, plus a test_ros_gz_bridge directory, so the split between transport, messages and testing is visible in the source layout.

## The version matrix is the real documentation

The most useful thing in this repository is a table, and it deserves to be read as the specification rather than as a footnote. It maps each ROS 2 distribution to a Gazebo version, a branch and a binary source. Humble pairs with Fortress, Garden and Harmonic, with Fortress binaries at packages.ros.org and Garden and Harmonic hosted at the gazebo packages repository. Jazzy pairs with Garden, where the binaries are only from source, or with Harmonic, where packages.ros.org serves them. Kilted pairs with Ionic and gets binaries from packages.ros.org. Lyrical pairs with Harmonic and with Ionic, both only from source, and with Jetty, which does have binaries at packages.ros.org. Rolling pairs with Harmonic and Ionic from source and with Jetty from packages.ros.org. Two footnotes carry the warnings. Binaries for the Humble pairings with Garden and Harmonic come from the packages.osrfoundation.org repository rather than packages.ros.org, and the note marks the Gazebo version on that row as having reached end-of-life, with the installation instructions pointing to the Gazebo docs. In practice, the table answers the only question that blocks an install, which is which Gazebo release goes with the ROS distro you already have.

## Installing the binaries and building from source

The binaries path starts by adding the ROS apt source with the ros2-apt-source package:

```bash
        sudo apt-get update && sudo apt-get install -y curl
        export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\" '{print $4}')
        curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
        sudo dpkg -i /tmp/ros2-apt-source.deb
        sudo apt-get update
```

Then the integration itself is one package:

```bash
        sudo apt install ros-rolling-ros-gz
```

For a source build, which is what the matrix requires for several pairings, you need ROS Rolling installed first, at least ROS-Base, and the matching Gazebo version is installed automatically when rosdep runs. Create the workspace and fetch the sources:

```bash
    mkdir -p ~/ws/src
    cd ~/ws/src
    git clone https://github.com/gazebosim/ros_gz.git -b ros2
```

Dependencies come next, and this step can pull in Gazebo itself:

```bash
    cd ~/ws
    rosdep install -r --from-paths src -i -y --rosdistro rolling
```

Finally, source the distribution and build:

```bash
    source /opt/ros/<distro>/setup.bash
    cd ~/ws
    colcon build
```

The steps are written for Linux and macOS. If rosdep fails to install the Gazebo libraries and you have not installed them before, the README points you to the Gazebo installation instructions.

## A memory hungry build and a set of shim packages

Two rough edges are worth knowing before you start. The first is the build. The README carries a tip explaining that the ros_gz library makes heavy use of templates, which causes compilers to consume a lot of memory, and that a build failing with c++: fatal error: Killed signal terminated program cc1plus should be retried with a sequential executor, adding that you might also have to set the MAKEFLAGS environment variable to limit the number of processors used to build a single package. On a shared build agent or a laptop with modest memory this is a realistic failure, not a theoretical one, and the fix is documented even if the underlying template usage is not. The second rough edge is naming history. The README notes that the ros_ign prefixed packages are shim packages that redirect to their ros_gz counterpart, and says that under most circumstances you want to be using the ros_gz counterpart. That matters for existing setups, because a workspace that still depends on ros_ign packages is running through a compatibility layer, and the advice for a new project is to depend on ros_gz directly. It also means that a build can succeed while the workspace is still using the older names, which is easy to miss when you are checking whether your migration actually finished.

## Where this is the wrong tool

The first wrong-tool case is ROS 1. The README directs ROS 1 and Gazebo compatibility questions to the noetic branch README, so a ROS 1 project is a different codebase with a different matrix, and adopting the ros2 branch for it will not work. The second case is a simulator other than Gazebo, since the entire package set exists to bridge Gazebo Transport to ROS and has no value outside that pairing. The third is a hardware-first workflow, because the bridge is built for simulation and carries the simulator's semantics, including the clock, so treating its timestamps as real time in a hardware pipeline is a mistake. The fourth is the version matrix itself. Several pairings are only available from source, and two of the Garden rows are marked as end-of-life or use with caution, so a team that wants a supported, binary-installed combination has to pick its ROS distro and Gazebo version together rather than choosing Gazebo first and hoping. If you are not willing to make that pairing decision, this repository is going to be a source build with version caveats rather than a package install.

## Maintenance, releases and what the release list tells you

The repository is not archived and the last push was on 2026-10-22, with the ros2 branch as the default and dedicated CI on that branch. The published releases, however, tell a different story, and it is worth reading them accurately. The listed releases are 0.3.0 from 2019-07-01, 0.2.2 from 2019-05-20 and 0.2.1 from 2019-05-13, which are from the era of the earlier naming and of the ROS 1 line. There is no recent GitHub release corresponding to the current ROS 2 work. That is not a sign of abandonment, it is a distribution model, because ROS 2 packages are versioned and shipped by the distribution itself, which is why the matrix points at packages.ros.org, at the Gazebo packages repository and at packages.osrfoundation.org rather than at a release page. The practical consequence is that you consume ros_gz as part of a ROS 2 distribution or as a source build, and the upgrade path follows your distro rather than a tag. The licence is Apache-2.0, which carries the usual attribution and patent terms, and the repository also has CONTRIBUTING.md and RELEASING.md for anyone working on the project itself. There is a project template repository for a ROS and Gazebo integrated setup, and a ROSCon 2022 talk linked for background.

## Conclusion

ros_gz is the right dependency if your pipeline pairs ROS 2 with Gazebo, and the compatibility matrix tells you exactly which pairing you can install as binaries rather than build from source. Do not adopt it if you need ROS 1, since that line lives on a separate noetic branch, and treat the Garden pairings marked as end-of-life with care. Before committing, check the row for your ROS 2 distro in the matrix, since several pairings, including Jazzy with Garden and both Lyrical entries with Harmonic and Ionic, are only available from source.

## FAQ

### Which Gazebo version works with my ROS 2 distro in ros_gz?

The README table maps each pairing. Humble works with Fortress, Garden and Harmonic, Jazzy with Garden and Harmonic, Kilted with Ionic, Lyrical with Harmonic, Ionic and Jetty, and Rolling with Harmonic, Ionic and Jetty. Some of those pairings are only available from source.

### How do I install ros_gz from binaries?

Add the ROS apt source using the ros2-apt-source package, then install the integration with apt. For Rolling the package is ros-rolling-ros-gz, and the branches for other distros are named after them, such as humble, jazzy, kilted and lyrical.

### What is the difference between ros_ign and ros_gz packages?

The README says the ros_ign prefixed packages are shim packages that redirect to their ros_gz counterpart, and that under most circumstances you want to use the ros_gz counterpart. A workspace still depending on ros_ign is therefore running through a compatibility layer.

### What should I do if the ros_gz build runs out of memory?

The README notes that the library makes heavy use of templates and that a failure showing cc1plus killed by a signal should be retried with a sequential executor, and that you might also have to limit the processors used for a single package with the MAKEFLAGS environment variable.

## Sources

- [gazebosim/ros_gz on GitHub](https://github.com/gazebosim/ros_gz)
- [License: Apache-2.0](https://github.com/gazebosim/ros_gz/blob/ros2/LICENSE)
- [Project website](https://gazebosim.org)
- [README](https://github.com/gazebosim/ros_gz/blob/ros2/README.md)
- [Releases](https://github.com/gazebosim/ros_gz/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gazebosim-ros-gz