Skip to main content

Environment Setup

This guide shows how to set up a ROS 2 development environment on Ubuntu.

ROS 2 currently maintains two stable releases:

  • Ubuntu 22.04

💡 Recommendation: Beginners should choose Humble (mature ecosystem); choose Jazzy if you want to learn the latest features.

System Environment​

Make sure the system Locale supports UTF-8 to avoid encoding issues during installation.

Ubuntu
locale

On a Chinese system, the output looks like zh_CN.UTF-8.

Enable Software Sources​

Enable the Universe Repository​

software-properties-common provides the add-apt-repository tool; the universe repository contains community-maintained open-source software that some ROS 2 dependencies rely on.

Ubuntu
sudo apt update && sudo apt install software-properties-common -y
sudo add-apt-repository universe

Add the ROS 2 Source​

It is recommended to use the official ROS GPG key and apt source directly (the current official approach). This does not depend on downloading a deb from GitHub Releases, making it more reliable on restricted networks or ARM platforms.

Ubuntu
sudo apt update && sudo apt install curl gnupg lsb-release -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /tmp/ros.key
sudo install -m 0755 -d /etc/apt/keyrings
sudo mv /tmp/ros.key /etc/apt/keyrings/ros-archive-keyring.gpg
sudo chmod a+r /etc/apt/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}}) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt update
tip

⚠️ Alternative (ros2-apt-source deb): If your network can access GitHub Releases normally, you may use the older official method of downloading the ros2-apt-source deb to configure the source automatically. Note that when extracting the version, do not use the awk -F'"' style (it can fail under nested quoting); use the more robust grep -oP instead:

Ubuntu
sudo apt update && sudo apt install curl -y
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -oP '"tag_name":\s*"\K[^"]+')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo ${UBUNTU_CODENAME:-${VERSION_CODENAME}})_all.deb"
sudo dpkg -i /tmp/ros2-apt-source.deb
sudo apt update

If ROS_APT_SOURCE_VERSION is empty (GitHub API rate limit or no network), visit ROS Apt Source Releases to get a version and set it explicitly, e.g. export ROS_APT_SOURCE_VERSION="1.2.0".

Install Development Tools​

ros-dev-tools includes essential tools such as colcon, rosdep, and catkin.

Ubuntu
sudo apt install ros-dev-tools -y

Install ROS 2​

Install the Base Version​

Includes communication libraries (rclpy, rclcpp), message packages, and CLI tools, without GUI. Suitable for servers / headless scenarios.

Ubuntu
sudo apt install ros-humble-ros-base -y

Install the Desktop Version​

Includes the ROS core + RViz visualization + demos + tutorials. Suitable for desktop / development users.

Ubuntu
sudo apt install ros-humble-desktop -y

Configure Environment Variables​

Load the ROS 2 workspace into the current shell environment — setting key variables such as ROS_DISTRO, ROS_PACKAGE_PATH, PATH, and LD_LIBRARY_PATH.

Ubuntu
source /opt/ros/humble/setup.bash

💡 If you don't want to source manually in every new terminal, add it to ~/.bashrc (pick the line matching your distro):

Ubuntu
echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc

Or make it apply to all users (root required):

Ubuntu
echo "source /opt/ros/jazzy/setup.bash" | sudo tee /etc/profile.d/ros2.sh > /dev/null

Verify the ROS 2 Environment​

📦 ros-base only includes the communication libraries and CLI tools — it does not ship the demo nodes demo_nodes_cpp / demo_nodes_py. Install the demo packages before running the talker/listener verification (pick the line matching your distro):

Ubuntu
sudo apt install ros-humble-demo-nodes-cpp ros-humble-demo-nodes-py -y

Open two terminals and run:

  • Terminal 1 (talker, C++ publisher)
Ubuntu
source /opt/ros/humble/setup.bash
ros2 run demo_nodes_cpp talker
  • Terminal 2 (listener, Python subscriber)
Ubuntu
source /opt/ros/humble/setup.bash
ros2 run demo_nodes_py listener

Method 2: Single-Terminal One-Shot Verification (great for scripts/containers)​

No need for two terminals — start talker and listener in one command:

Ubuntu
source /opt/ros/humble/setup.bash
ros2 run demo_nodes_cpp talker & sleep 2; ros2 run demo_nodes_py listener & sleep 4; kill %1 %2

If the listener keeps printing I heard: [Hello World: N], it means ROS 2's publish/subscribe, topic discovery, and the C++/Python client libraries are all working properly.

Join Us