Native Installation#

This page walks you through installing Gazebo Harmonic and building the ROSbot simulation packages directly on your system – no Docker required.

Warning

Gazebo Harmonic and Gazebo Classic cannot coexist on the same system. If you need Gazebo Classic for another course, use the Docker Installation method instead.

Prerequisites#

  • Ubuntu 24.04 with ROS 2 Jazzy already installed

  • colcon and vcs build tools:

    sudo apt install -y python3-colcon-common-extensions python3-vcstool

Step 1: Install Gazebo Harmonic#

Install Gazebo Harmonic from packages

Add the Gazebo package repository:

sudo curl https://packages.osrfoundation.org/gazebo.gpg \
    --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] \
    http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" \
    | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null

Install Gazebo Harmonic:

sudo apt update
sudo apt install -y gz-harmonic

Verify the installation:

gz sim --version

You should see the Gazebo Harmonic version printed.

Install the ROS 2–Gazebo bridge packages:

sudo apt install -y ros-jazzy-ros-gz

Step 2: Create and Build the Workspace#

Clone the course workspace

The course repository already bundles the ROSbot simulation packages (husarion_components_description, husarion_controllers, husarion_gz_worlds, and rosbot_ros) under lecture11/ – there is no need to create a separate rosbot_ws or to pull them in manually with vcs import.

Clone the course repository into your workspace:

mkdir -p ~/enpm605_ws
cd ~/enpm605_ws
git clone https://github.com/zeidk/enpm605-spring-2026-ros.git src
Install dependencies and build

Install all required ROS 2 dependencies:

source /opt/ros/jazzy/setup.bash
rosdep update
sudo apt update && rosdep install -i --from-path src --rosdistro $ROS_DISTRO --ignore-src -y --skip-keys "micro_ros_agent python3-ftdi"

Warning

You must source /opt/ros/jazzy/setup.bash before building. If you skip this step, the workspace overlay will not be able to find system packages like ros_gz_bridge, and the simulation launch will fail.

Build the workspace up to the Lecture 11 meta-package (this pulls in every ROSbot simulation package and the lecture demos in the correct order):

colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to lecture11_meta

  • --symlink-install creates symbolic links instead of copying files, so changes to Python scripts and launch files take effect without rebuilding.

  • -DCMAKE_BUILD_TYPE=Release enables compiler optimizations.

  • --packages-up-to lecture11_meta builds lecture11_meta and all of its transitive dependencies (the husarion and rosbot packages, plus frame_demo and robot_control_demo).

The build may take several minutes on the first run.

Source the workspace:

source install/setup.bash

Tip

Add the following line to your ~/.bashrc so the workspace is sourced automatically in every new terminal:

source ~/enpm605_ws/install/setup.bash

Step 3: Launch the Simulation#

With the workspace sourced, launch the simulation using the shared instructions on the Launching the Simulation page.

Troubleshooting#

gz sim command not found

Gazebo Harmonic is not installed or not on your PATH.

  • Verify the installation with apt list --installed | grep gz-harmonic.

  • Ensure the OSRF repository was added correctly (see Step 1).

  • Re-run sudo apt update && sudo apt install -y gz-harmonic.

rosdep install fails with missing keys

Some dependencies may not be available in the default rosdep sources.

  • Ensure you ran rosdep update before rosdep install.

  • Try adding the --skip-keys flag for known missing keys:

rosdep install --from-paths src --ignore-src -y --skip-keys "gz-harmonic micro_ros_agent"
colcon build fails with CMake errors

  • Make sure you sourced ROS 2 before building:

source /opt/ros/jazzy/setup.bash

  • Ensure all dependencies were installed with rosdep install.

  • Delete the build/, install/, and log/ directories and rebuild:

rm -rf build/ install/ log/
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release --packages-up-to lecture11_meta
Gazebo crashes or shows a black screen

  • Check if your GPU drivers are working:

glxinfo | grep "OpenGL renderer"

If the renderer shows llvmpipe or software, your GPU drivers are not properly installed. - For NVIDIA GPUs, ensure the proprietary driver is installed:

sudo ubuntu-drivers install

  • Try running Gazebo with software rendering as a workaround:

export LIBGL_ALWAYS_SOFTWARE=1
ros2 launch rosbot_gazebo simulation.yaml
package 'rosbot_gazebo' not found

The workspace is not sourced.

  • Run source ~/enpm605_ws/install/setup.bash in your terminal.

  • Verify the package exists:

ros2 pkg prefix rosbot_gazebo