Getting Started with Gazebo?#

Welcome to Gazebo!

When you’re ready, follow the next few steps to get up and running with simulation using Gazebo.

Step 1: Install#

Important

If you are a ROS user, please first read our tutorial on ROS/Gazebo installation

The recommended installation for new users is the use of binary packages available for the platform to use:

Platform

Gazebo Versions

Ubuntu 24.04 Noble

Gazebo Harmonic (recommended), (recommended if using ROS 2 Jazzy) and Gazebo Ionic

Ubuntu 22.04 Jammy

Gazebo Harmonic (recommended), Gazebo Garden and Gazebo Fortress (recommended if using ROS 2 Humble or Iron)

Ubuntu 20.04 Focal

Gazebo Garden (recommended), Gazebo Fortress and Gazebo Citadel

Ubuntu 18.04 Bionic

Gazebo Citadel

Mac Ventura

Gazebo Harmonic (recommended), Gazebo Garden, Gazebo Fortress and Gazebo Citadel

Mac Monterey

Gazebo Harmonic (recommended), Gazebo Garden, Gazebo Fortress and Gazebo Citadel

Windows

Support via Conda-Forge is not fully functional, as there are known runtime issues see this issue for details.

If the desired platform is not listed above or if a particular feature in a given Gazebo release is needed, there is an installation package per release available with all the installation options:

Step 2: Run#

After installing Gazebo in Step 1, you can launch Gazebo Sim, a 3D robotics simulator, from a terminal.

  • If you are on macOS, see specific instructions in the macOS section.

Launch Gazebo by running:

gz sim shapes.sdf  # Fortress and Citadel use "ign gazebo" instead of "gz sim"

This command will launch both the Sim server and Sim GUI with a world that contains three simple shapes.

Add the -v 4 command line argument to generate error, warning, informational, and debugging messages on the console.

gz sim shapes.sdf -v 4  # Fortress and Citadel use "ign gazebo" instead of "gz sim"

Gazebo Sim can also be run headless, i.e. without the GUI, by using the -s (server only) flag.

gz sim -s shapes.sdf -v 4  # Fortress and Citadel use "ign gazebo" instead of "gz sim"

Similarly, the GUI can be run independently using the -g (gui only) flag. On start, the GUI will attempt to connect to a server instance. If a server is not available, then you will see just a blank screen until a server instances is started.

Step 3: Create your own world#

SDF is used to specify the contents of simulation. Take a look at the available SDF tutorials to get started.

Modifying an existing SDF world is also a good way to get started. Gazebo Sim ships with a number of example SDF worlds that you can freely copy and modify. These example SDF files are installed. Many of the SDF files also have instructions located at the top of the SDF file. The instructions typically contain information about how to run Sim with the SDF file in order to experience a particular feature.

There are a wide variety of simulation resources at your disposal on https://app.gazebosim.org/fuel. If you find a model you’d like to use, then click on the <> icon in the model description page, highlighted in the image below, to copy an SDF snippet into your clipboard. This snippet can be pasted directly into your custom SDF file.

SDF model snippet

Step 4: Explore and learn#

This tutorial has covered the basics of getting started with Gazebo. Starting with Citadel, there are more versioned tutorials covering the basics of the GUI, creating worlds and robots, and more.

Each Gazebo library also has a set of tutorials and examples. Explore these resources, and don’t forget to ask questions and find solutions at answers.gazebosim.org.

macOS#

On macOS, you will need to run Gazebo using two terminals, one for the server and another for the GUI:

# launch server in one terminal
gz sim -v 4 shapes.sdf -s  # Fortress and Citadel use "ign gazebo" instead of "gz sim"

# launch gui in a separate terminal
gz sim -v 4 -g  # Fortress and Citadel use "ign gazebo" instead of "gz sim"

The GUI on macOS is currently known to be unstable. Basic interaction with the 3D scene such as camera view control and translation / rotation tools should be functional. However, some GUI plugins like the Component Inspector may be buggy and interaction with certain GUI elements may cause the GUI to crash. Please ticket an issue at gazebosim/gz-sim if you run into GUI problems on macOS.