ROS2 Setup Guide for Robot Learning

Step-by-step guide to installing ROS2 Humble or Jazzy on Ubuntu for robot learning, data collection, and teleoperation with OpenArm and LeRobot.

Beginner ⏱ 30–45 minutes Updated April 2026

1. System Check 2. Install ROS2 3. Build Tools 4. Workspace 5. Robot Packages 6. Test 7. OpenArm Config 8. LeRobot Bridge

Prerequisites

Ubuntu 22.04 LTS (recommended) or Ubuntu 24.04 LTS
At least 16 GB RAM (32 GB recommended for ML workloads)
50 GB free disk space
NVIDIA GPU with 8+ GB VRAM (for downstream ML tasks)
Internet connection for package downloads
Basic familiarity with the Linux terminal

What you will set up

By the end of this tutorial, you will have a fully working ROS2 installation with colcon build tools, a workspace structure, MoveIt2 and ros2-control for robot arm manipulation, and a bridge to LeRobot for data collection. This is the foundation for every other tutorial on this site.

Check System Requirements

Before installing anything, verify your system meets the requirements. Open a terminal and run these checks:

# Check Ubuntu version (need 22.04 or 24.04) lsb_release -a # Check available RAM free -h # Check available disk space df -h / # Check NVIDIA GPU (if applicable) nvidia-smi

You should see Ubuntu 22.04 or 24.04, at least 16 GB RAM, and 50 GB+ free disk space. If nvidia-smi is not found, install NVIDIA drivers first:

sudo ubuntu-drivers autoinstall sudo reboot

Tip: ROS2 Humble targets Ubuntu 22.04 and ROS2 Jazzy targets Ubuntu 24.04. Using the matching Ubuntu version avoids compatibility issues. If you are starting fresh, Ubuntu 22.04 + Humble is the safest path for robot learning in 2026.

Install ROS2 Humble (or Jazzy)

Set up locale, add the ROS2 apt repository, and install ROS2. These commands are for Humble on 22.04 — replace humble with jazzy and jammy with noble if you are on 24.04.

# Set locale to UTF-8 (required by ROS2) sudo apt update && sudo apt install -y locales sudo locale-gen en_US en_US.UTF-8 sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 export LANG=en_US.UTF-8 # Add the ROS2 GPG key sudo apt install -y software-properties-common sudo add-apt-repository universe sudo apt update && sudo apt install -y curl sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \ -o /usr/share/keyrings/ros-archive-keyring.gpg # Add the repository echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" \ | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null # Install ROS2 Humble Desktop (includes RViz, demo nodes, etc.) sudo apt update sudo apt install -y ros-humble-desktop

This will take 5–15 minutes depending on your connection. Once done, source the setup file:

# Source ROS2 (add to .bashrc for persistence) source /opt/ros/humble/setup.bash echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc

Install Colcon Build Tools and rosdep

Colcon is the standard build tool for ROS2 workspaces. rosdep resolves and installs package dependencies automatically.

# Install colcon and build essentials sudo apt install -y \ python3-colcon-common-extensions \ python3-rosdep \ python3-vcstool \ build-essential \ cmake \ git # Initialize rosdep (only needed once) sudo rosdep init rosdep update

Note: If sudo rosdep init says "already initialized", that is fine — just run rosdep update and continue.

Create a ROS2 Workspace

A ROS2 workspace is a directory where you clone, build, and develop packages. The standard convention is ~/ros2_ws.

# Create workspace directories mkdir -p ~/ros2_ws/src cd ~/ros2_ws # Run an empty build to verify colcon works colcon build source install/setup.bash # Add workspace sourcing to .bashrc echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc

You should see output like:

Summary: 0 packages finished [0.5s]

This means colcon is working. Your workspace structure is now:

~/ros2_ws/
  ├── build/      # Build artifacts
  ├── install/    # Installed packages (sourced by setup.bash)
  ├── log/        # Build logs
  └── src/        # Your packages go here

Install Common Robot Packages

These packages are used in nearly every robot learning pipeline — arm control, motion planning, navigation, and sensor processing.

# ros2-control: hardware abstraction for actuators and sensors sudo apt install -y ros-humble-ros2-control ros-humble-ros2-controllers # MoveIt2: motion planning for robot arms sudo apt install -y ros-humble-moveit # Nav2: navigation stack (for mobile robots) sudo apt install -y ros-humble-navigation2 ros-humble-nav2-bringup # Camera and sensor packages sudo apt install -y \ ros-humble-realsense2-camera \ ros-humble-image-transport \ ros-humble-compressed-image-transport \ ros-humble-cv-bridge # URDF and visualization tools sudo apt install -y \ ros-humble-joint-state-publisher-gui \ ros-humble-robot-state-publisher \ ros-humble-xacro \ ros-humble-rviz2

Tip: You do not need all of these for every project. Nav2 is only for mobile robots, and MoveIt2 is only for arms. Install what you need, but having them available saves time later.

Test Your Installation

Verify everything works by running the classic talker/listener demo. Open two terminals:

Terminal 1 — Start the talker:

ros2 run demo_nodes_cpp talker

Terminal 2 — Start the listener:

ros2 run demo_nodes_cpp listener

You should see the talker publishing messages and the listener receiving them:

[INFO] [talker]: Publishing: 'Hello World: 1'
[INFO] [talker]: Publishing: 'Hello World: 2'
---
[INFO] [listener]: I heard: [Hello World: 1]
[INFO] [listener]: I heard: [Hello World: 2]

Also verify the key tools work:

# List active topics ros2 topic list # Check ROS2 environment ros2 doctor --report

Configure for OpenArm and Robot Arms

If you are using OpenArm or another robot arm, you need to set up the URDF description and ros2-control configuration.

# Clone the OpenArm ROS2 package into your workspace cd ~/ros2_ws/src git clone https://github.com/svrc-robotics/openarm_ros2.git # Install dependencies cd ~/ros2_ws rosdep install --from-paths src --ignore-src -r -y # Build the workspace colcon build --symlink-install source install/setup.bash

Launch the robot description and visualize it in RViz2:

# Launch robot_state_publisher with URDF ros2 launch openarm_description display.launch.py

RViz2 should open showing the OpenArm model. You can move the joints using the joint_state_publisher_gui sliders to verify the URDF is correct.

Tip: For other robot arms (UR5, Franka, Koch, SO-100), the same workflow applies — clone the manufacturer's ROS2 description package into ~/ros2_ws/src, run rosdep install, and build.

Connect to LeRobot for Data Collection

LeRobot is Hugging Face's toolkit for robot learning. You can bridge ROS2 topics to LeRobot for recording teleoperation data.

# Install LeRobot (in a Python virtual environment) python3 -m venv ~/lerobot_env source ~/lerobot_env/bin/activate pip install lerobot # Verify installation python3 -c "import lerobot; print(lerobot.__version__)"

Test that ROS2 topics are visible to LeRobot by checking the joint states:

# In one terminal: run the robot ros2 launch openarm_bringup openarm.launch.py # In another: verify joint state topic is publishing ros2 topic echo /joint_states --once

Your ROS2 setup is now complete and ready for data collection. The next step is to configure LeRobot to record demonstrations from your robot.

Next: Collect Robot Training Data

Ready to start recording demonstrations? Follow our complete data collection tutorial to set up teleoperation, record episodes, and prepare your dataset for VLA fine-tuning.

Troubleshooting

Locale Error: "Cannot set LC_ALL to default locale"

Run sudo locale-gen en_US.UTF-8 and then sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8. Log out and back in, then retry the installation.

GPG Key Error: "The following signatures couldn't be verified"

The ROS2 GPG key may have changed. Re-download it: sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg and then sudo apt update.

Missing Dependencies: "rosdep could not find package"

Run rosdep update first. If the error persists, install the missing system dependency manually with sudo apt install <package-name>. Check the ROS2 Discourse forums for package-specific fixes.

colcon build fails with "CMake Error"

Make sure you sourced ROS2 before building: source /opt/ros/humble/setup.bash. Also verify build-essential and cmake are installed: sudo apt install -y build-essential cmake.

nvidia-smi: "NVIDIA-SMI has failed"

Your NVIDIA driver may need reinstalling. Run sudo apt purge nvidia-*, then sudo ubuntu-drivers autoinstall, and reboot. Verify with nvidia-smi after reboot.

Next Steps

Your ROS2 environment is ready. Here is what to do next depending on your goal:

Collect training data: Follow the teleoperation data collection guide
Get started with LeRobot: See the LeRobot quickstart
Set up OpenArm: Follow the OpenArm first demo tutorial
Fine-tune a VLA model: Jump to VLA fine-tuning guide (after collecting data)

Frequently Asked Questions

ROS2 Humble (LTS, supported until May 2027) is the safest choice for production robot learning pipelines. ROS2 Jazzy (released May 2024) offers newer features but has a smaller package ecosystem. Most LeRobot and OpenVLA integrations target Humble first.

An NVIDIA GPU with at least 8 GB VRAM is strongly recommended. You need it for real-time camera processing, CUDA-accelerated inference, and running VLA models during deployment. ROS2 itself runs fine on CPU, but downstream ML tasks require GPU.

ROS2 officially supports Ubuntu Linux. While Humble has experimental macOS and Windows builds, most robot learning tooling (LeRobot, OpenVLA, MoveIt2) is only tested on Ubuntu. Use a native Ubuntu install or a Docker container for the best experience.

Plan for at least 30 GB. ROS2 Desktop takes about 3 GB, MoveIt2 adds 2–4 GB, and ML dependencies (PyTorch, CUDA toolkit) can take 15–20 GB. Training data storage is additional — budget 100 GB+ if you plan to collect teleoperation datasets.

ros2-control is a hardware abstraction layer that manages real-time communication with robot actuators and sensors. MoveIt2 is a motion planning framework that generates collision-free trajectories. They work together: MoveIt2 plans the path, ros2-control executes it on the hardware.

Was this tutorial helpful?