px4io/px4-sitl-gazebo-ros2 repository overview

⁠PX4 SITL with ROS 2 and Gazebo Harmonic

A ready-to-use environment for developing ROS 2 applications with PX4 Autopilot and Gazebo Harmonic. Run packaged PX4 firmware with Gazebo worlds, vehicle models, and simulated sensors, without compiling PX4.

Use this image when your ROS 2 application needs Gazebo simulation, including visual environments and sensor-driven workflows. Headless operation is supported; displaying the Gazebo GUI requires host display configuration.

⁠Included

• Ubuntu 24.04 and ROS 2 Jazzy.
• PX4 SITL and Gazebo Harmonic, with packaged models and worlds; the default vehicle is the X500 quadrotor.
• Micro XRCE-DDS Agent v2.4.3 for communication between PX4 and ROS 2.
• Prebuilt px4_msgs matching the packaged PX4 firmware.
• The PX4 ROS 2 Interface Library⁠, including examples and development tools.

Images are available for Linux amd64 and arm64.

⁠Quick start: headless simulation

Run these commands in separate host terminals.

Terminal 1: start the container and DDS Agent.

docker run --rm -it --name px4-gazebo-ros2 \
  px4io/px4-sitl-gazebo-ros2:latest MicroXRCEAgent udp4 -p 8888

Terminal 2: start PX4 and headless Gazebo.

docker exec -it px4-gazebo-ros2 \
  /usr/local/bin/ros2-entrypoint.sh env HEADLESS=1 px4-gazebo

Terminal 3: list ROS 2 topics.

docker exec -it px4-gazebo-ros2 \
  /usr/local/bin/ros2-entrypoint.sh ros2 topic list

PX4, the Agent, and ROS 2 communicate inside the same container; this example does not require host networking. Connecting ROS nodes outside the container requires additional DDS networking configuration.

Without an explicit command, the image opens Bash with ROS 2 and the workspace at /opt/px4_ros2 already sourced. PX4, Gazebo, and the Agent do not start automatically.

For the Gazebo GUI, follow the container display setup guide⁠ and leave HEADLESS unset.

For reproducible environments, pin an image digest rather than relying on the moving latest tag. If you modify PX4 firmware or its message definitions, rebuild the ROS workspace to match; do not assume the bundled messages are compatible.

⁠Related images and documentation

• PX4 SITL with SIH and ROS 2⁠ is the lighter alternative when you do not need Gazebo.
• ghcr.io/px4/px4-dev-ros2:main-jazzy provides the standalone source-build toolchain used by PX4 ROS integration CI, without bundled firmware or a prebuilt ROS workspace.
• PX4 prebuilt simulation packages⁠
• PX4 ROS 2 guide⁠
• Container source⁠