How to Load a World File into Gazebo – ROS 2


In this tutorial, I will show you how to load a .world file into Gazebo. 

You can learn all about world files at this link.

Real-World Applications

Simulating a world has a number of real-world robotic applications: 

  • Ground Delivery
  • Hospitals and Medical Centers
  • Hotels (Room Service)
  • Offices
  • Restaurants
  • Warehouses
  • And more…

Roboticists like to simulate robots in simulated worlds in order to test out different algorithms. You can imagine the cost of making mistakes with a physical robot can be high (e.g. crashing a mobile robot into a wall at high speed means lost money).

You can get all the code for this tutorial here.

Let’s get started!


  • ROS 2 Foxy Fitzroy installed on Ubuntu Linux 20.04 or newer. I am using ROS 2 Galactic, which is the latest version of ROS 2 as of the date of this post.
    • If you are using another ROS 2 distribution, you will need to replace ‘galactic’ with the name of your distribution everywhere I mention ‘galactic’ in this tutorial. 
    • I highly recommend you get the newest version of ROS 2. If you are using a newer version of ROS 2, you can still follow all the steps in this tutorial. Everything will work just fine.
  • You have already created a ROS 2 workspace. The name of our workspace is “dev_ws”, which stands for “development workspace.” 
  • (Optional) You have a package named two_wheeled_robot inside your ~/dev_ws/src folder, which I set up in this post. If you have another package, that is fine.


Quick Start

The easiest way to load a world is via the command line. 

Open a new terminal window.

Type the following command to open up a world named This file is one of the built-in worlds that comes with the Gazebo installation (I am using Gazebo 11).

gazebo worlds/

You can see a list of all the built-in worlds in this GitHub repository.

The world files are located in your /usr/share/gazebo-11/worlds directory.

The models (i.e. models for the objects that are inside your world) are located inside this directory:


Where focalfossa is the name of your Linux environment.

When you want to close the world, go back to the terminal, and type:


Your Own World

If you have your own world, you can follow the instructions on this post to test it in Gazebo.

Alternatively, you can launch Gazebo using the following command.


Then go to the Insert tab, and start inserting items inside the empty world. 


Once you’re done, you can save the world file by going to File ->Save World As.

Using a Launch File

Example – Cafe World

Let’s launch the cafe world we saw earlier using a ROS 2 launch file.

I want to copy the file to the worlds folder of my ROS 2 package.

cd /usr/share/gazebo-11/worlds
cp ~/dev_ws/src/two_wheeled_robot/worlds

The syntax is:

cp <world file> <path to the worlds folder inside your ROS 2 package>

cd ~/dev_ws/src/two_wheeled_robot/worlds

You will see the file has various links to other models and mesh files in it. Let’s move those files over to our package so that everything is all inside our two_wheeled_robot package (or whatever ROS 2 package you’re using).

Start from the top of the file.

The first model we need to move over is the ground_plane model.

cd ~/.gazebo/models
cp -r ground_plane ~/dev_ws/src/two_wheeled_robot/models

Now let’s copy over the other models.

cp -r cafe ~/dev_ws/src/two_wheeled_robot/models
cp -r cafe_table ~/dev_ws/src/two_wheeled_robot/models

Now let’s create a launch file.

colcon_cd two_wheeled_robot
cd launch

Write this code inside the file.

# Author: Addison Sears-Collins
# Date: September 19, 2021
# Description: Load a world file into Gazebo.

import os
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument, IncludeLaunchDescription
from launch.conditions import IfCondition, UnlessCondition
from launch.launch_description_sources import PythonLaunchDescriptionSource
from launch.substitutions import Command, LaunchConfiguration, PythonExpression
from launch_ros.actions import Node
from launch_ros.substitutions import FindPackageShare

def generate_launch_description():

  # Set the path to the Gazebo ROS package
  pkg_gazebo_ros = FindPackageShare(package='gazebo_ros').find('gazebo_ros')   
  # Set the path to this package.
  pkg_share = FindPackageShare(package='two_wheeled_robot').find('two_wheeled_robot')

  # Set the path to the world file
  world_file_name = ''
  world_path = os.path.join(pkg_share, 'worlds', world_file_name)
  # Set the path to the SDF model files.
  gazebo_models_path = os.path.join(pkg_share, 'models')
  os.environ["GAZEBO_MODEL_PATH"] = gazebo_models_path

  # Launch configuration variables specific to simulation
  headless = LaunchConfiguration('headless')
  use_sim_time = LaunchConfiguration('use_sim_time')
  use_simulator = LaunchConfiguration('use_simulator')
  world = LaunchConfiguration('world')

  declare_simulator_cmd = DeclareLaunchArgument(
    description='Whether to execute gzclient')
  declare_use_sim_time_cmd = DeclareLaunchArgument(
    description='Use simulation (Gazebo) clock if true')

  declare_use_simulator_cmd = DeclareLaunchArgument(
    description='Whether to start the simulator')

  declare_world_cmd = DeclareLaunchArgument(
    description='Full path to the world model file to load')
  # Specify the actions
  # Start Gazebo server
  start_gazebo_server_cmd = IncludeLaunchDescription(
    PythonLaunchDescriptionSource(os.path.join(pkg_gazebo_ros, 'launch', '')),
    launch_arguments={'world': world}.items())

  # Start Gazebo client    
  start_gazebo_client_cmd = IncludeLaunchDescription(
    PythonLaunchDescriptionSource(os.path.join(pkg_gazebo_ros, 'launch', '')),
    condition=IfCondition(PythonExpression([use_simulator, ' and not ', headless])))

  # Create the launch description and populate
  ld = LaunchDescription()

  # Declare the launch options

  # Add any actions

  return ld

Save the file, and close it.

Go to your root directory.

cd ~/dev_ws

Build the package.

colcon build

Open a new terminal window.

Run the launch file using the following command:

ros2 launch two_wheeled_robot

Here is the output. You should see the actors walking around the cafe.



In summary, the procedure for creating a world entails the following steps:

  1. Create the .world file inside the worlds folder of your package.
  2. Add the SDF models to the models folder of your package.
  3. Edit the launch file.
  4. Build the package.
  5. Launch the world.