Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PX4/PX4-Autopilot/llms.txt

Use this file to discover all available pages before exploring further.

Gazebo (formerly Gazebo Ignition) is the recommended 3D simulator for PX4 on Ubuntu 22.04 and later. It supersedes Gazebo Classic with more advanced rendering, a broader sensor library, and a larger model ecosystem. PX4 communicates with Gazebo directly via Gazebo Transport — no MAVLink bridge is required. A single make command builds PX4, launches the Gazebo client, and connects everything automatically.
Gazebo Classic is being downgraded to community-supported status. Start new projects with Gazebo (the commands below all use the gz_ prefix). If you have existing Gazebo Classic workflows, they continue to work but will not receive core team maintenance going forward.

​
Installation

Gazebo Harmonic is installed automatically on Ubuntu 22.04 as part of the standard PX4 development environment setup. On Ubuntu 24.04, Harmonic, Ionic, and Jetty are all supported; the latest installed release is used by default. 
# Install the full PX4 development environment including Gazebo
bash ./Tools/setup/ubuntu.sh
Gazebo Harmonic cannot be installed on Ubuntu 20.04 or earlier. On Ubuntu 20.04, use Gazebo Classic or upgrade your OS to 22.04.

​
Launching a simulation

Run PX4 SITL with Gazebo using a make target. All Gazebo targets use the gz_ prefix: 
cd /path/to/PX4-Autopilot
make px4_sitl gz_x500
This builds PX4, starts the Gazebo client with the x500 quadrotor model, and launches the PX4 SITL instance. QGroundControl detects the vehicle automatically on UDP port 14550.

​
Available vehicles

VehicleMake commandAutostart ID
Quadrotor (x500)make px4_sitl gz_x5004001
x500 with depth camera (front)make px4_sitl gz_x500_depth4002
x500 with visual odometrymake px4_sitl gz_x500_vision4005
x500 with 1D LiDAR (down)make px4_sitl gz_x500_lidar_down4016
x500 with 2D LiDARmake px4_sitl gz_x500_lidar_2d4013
x500 with gimbal (front)make px4_sitl gz_x500_gimbal4019
Standard VTOLmake px4_sitl gz_standard_vtol4004
Plane (RC Cessna)make px4_sitl gz_rc_cessna4003
Advanced planemake px4_sitl gz_advanced_plane4008
Quad tailsitter VTOLmake px4_sitl gz_quadtailsitter4018
Tiltrotor VTOLmake px4_sitl gz_tiltrotor4020
Differential rovermake px4_sitl gz_rover_differential50000
Ackermann rovermake px4_sitl gz_rover_ackermann51000
Mecanum rovermake px4_sitl gz_rover_mecanum52000
All vehicle models and worlds are pulled from the Gazebo Models Repository as a git submodule. Run git submodule update --init --recursive if models are missing after a fresh clone.

​
Specifying a world

By default, Gazebo launches with the default empty world. Pass a world name via the PX4_GZ_WORLD environment variable: 
PX4_GZ_WORLD=baylands make px4_sitl gz_x500
Available worlds include default, baylands, lawn, walls, windy, and others located in the Gazebo models repository. You can also point to a custom SDF world file by providing its full path.

​
Standalone mode

You can launch PX4 SITL and Gazebo in separate terminals. This is useful when Gazebo is running on a different host or when you need to restart PX4 without restarting the simulator.
1

Start Gazebo server

Launch the Gazebo server with the desired world and vehicle model:
gz sim -r default.sdf
2

Start PX4 SITL

In a second terminal, start PX4 and point it at the running Gazebo instance:
PX4_GZ_STANDALONE=1 make px4_sitl gz_x500

​
Multi-vehicle simulation

Gazebo supports spawning multiple PX4 instances in the same world. Each instance gets its own MAVLink port, allocated sequentially from 14540 for offboard APIs and 14550 for QGroundControl. Use the provided helper script to launch multiple vehicles: 
Tools/simulation/gazebo-classic/sitl_multiple_run.sh -m iris -n 4
For Gazebo (not Classic), spawn additional instances by exporting PX4_SIM_MODEL and running separate make calls with distinct px4_instance values: 
# Instance 0 — quadrotor
PX4_SYS_AUTOSTART=4001 PX4_GZ_MODEL=x500 ./build/px4_sitl_default/bin/px4 -i 0

# Instance 1 — plane
PX4_SYS_AUTOSTART=4003 PX4_GZ_MODEL=rc_cessna ./build/px4_sitl_default/bin/px4 -i 1
Each instance listens on its own MAVLink ports. QGroundControl can connect to all instances simultaneously.

​
ROS 2 integration

Gazebo SITL integrates with ROS 2 through the uXRCE-DDS bridge, which maps PX4 uORB topics to ROS 2 topics bidirectionally. No MAVLink-to-ROS bridge (like MAVROS) is required.
1

Start the simulation

Launch Gazebo SITL as usual:
make px4_sitl gz_x500
2

Start the uXRCE-DDS agent

In a separate terminal, start the Micro XRCE-DDS Agent:
MicroXRCEAgent udp4 -p 8888
3

Verify ROS 2 topics

In a third terminal, list the available PX4 topics on the ROS 2 graph:
ros2 topic list
You should see topics such as /fmu/out/vehicle_local_position and /fmu/in/vehicle_command.
The uXRCE-DDS bridge is enabled by default in PX4 SITL builds. On real hardware you must set UXRCE_DDS_CFG to configure the transport.

​
Running faster than real time

Set PX4_SIM_SPEED_FACTOR to run the simulation at a multiple of real time. PX4 and Gazebo run in lockstep, so any speed factor is safe: 
PX4_SIM_SPEED_FACTOR=2 make px4_sitl gz_x500

​
Overriding PX4 parameters at launch

Any PX4 parameter can be overridden via environment variables prefixed with PX4_PARAM_: 
export PX4_PARAM_EKF2_EN=0
export PX4_PARAM_ATT_EN=1
make px4_sitl gz_x500
This is useful for testing different estimators or failsafe thresholds without editing configuration files.

Build docs developers (and LLMs) love

Get started for freeTalk to us