If you’re getting started with ROS 2 on Ubuntu 24.04 LTS, one of the very first things you’ll need to do is create a workspace. A workspace is simply a folder where you keep all your ROS 2 packages, build them, and manage your development environment.
In this guide, we’ll walk through — step by step — how to set up a clean, organized ROS 2 workspace using colcon, the official build tool for ROS 2.
Let’s create a directory to hold our ROS 2 projects.
In your terminal, run:
mkdir -p ~/ros2_ws/src
Here’s what this does:
mkdir -p creates the directory (and any necessary parent folders).
~/ros2_ws/ is your workspace folder (you can name it differently if you want, but ros2_ws is a popular convention).
src/ is a subfolder where all your ROS 2 packages will go.
Before you can use ROS 2 tools like ros2 or colcon, your terminal needs to know where to find them. This is done by sourcing the ROS 2 setup script:
source /opt/ros/jazzy/setup.bash
If you added this command to your ~/.bashrc earlier, it will already run automatically in new terminals. But it’s good practice to check before moving on.
Even though there are no packages yet, it’s a good idea to build the workspace at this point. This verifies that your build system is working properly and sets up the necessary build/, install/, and log/ directories.
Move into your workspace’s root directory:
cd ~/ros2_ws
Then run:
colcon build
What happens here:
colcon looks inside the src/ folder for any packages to build.
Since there aren’t any yet, it’ll display a message like “No packages found” — which is exactly what we expect for now.
It still creates the necessary directories:
build/ — for temporary build files.
install/ — for compiled packages and environment setup scripts.
log/ — for logs generated during builds and execution.
After each build, you need to source your workspace’s local setup script so that your terminal recognizes the packages you’ve built (or will build).
Run:
source ~/ros2_ws/install/setup.bash
Why this matters:
ROS 2 allows multiple workspaces to exist on your system, and each workspace can have its own packages and dependencies. Sourcing the install/setup.bash from your workspace tells ROS 2 to prioritize the packages in this workspace when running commands.
To make sure your workspace is properly set up:
cd ~/ros2_ws
colcon list
Since there are no packages yet, it won’t list anything — and that’s fine. No errors means your workspace is set up correctly.
If you want to automate this process next time, here’s the entire setup sequence you can copy-paste into your terminal:
# Create the workspace directory
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
# Source ROS 2 environment
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrc
# Build the (empty) workspace
colcon build
# Source your workspace environment
echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc
source ~/ros2_ws/install/setup.bash
# Verify the workspace
colcon list
