Skip to content

ROS2 Humble Installation Guide

This document uses the FishROS one-click ROS2 installer to simplify setup.

👏 Thanks to the FishROS team (fishros.com) for providing this convenient installer.

📋 Installation Overview

Step Content Estimated Time
1️⃣ Switch package mirrors 5-10 minutes
2️⃣ Install ROS2 Humble 20-30 minutes
3️⃣ Configure rosdep 5-10 minutes
4️⃣ Update system environment 1-2 minutes
5️⃣ Test and verify 5 minutes

Total time: about 40-60 minutes (depends on network speed)

⚙️ System Requirements

Item Requirement
OS Ubuntu 22.04 LTS
ROS2 Version Humble Hawksbill
Disk Space At least 10 GB free space
Network Stable internet connection

🚀 Installation Steps

Step 1️⃣: Switch Mirrors

Purpose: Use domestic mirrors to speed up package downloads.

Command:

wget http://fishros.com/install -O fishros && . fishros

Operation flow:

1. Enter 5  -> One-click system source configuration
   ↓
2. Enter 2  -> Replace system source and clean third-party sources
   ↓
3. Enter 1  -> Add ROS/ROS2 source

Mirror selection notes:

Prompt Recommended action Notes
Choose fastest mirror Enter 1 Auto-test and pick the fastest source
Mirror list Choose USTC or Tsinghua Usually faster in mainland China

✅ Completion sign: "source configured successfully" or similar message appears

Step 2️⃣: Install ROS2 Humble

Purpose: Install ROS2 Humble Desktop version (includes RViz, Gazebo, etc.).

Command:

wget http://fishros.com/install -O fishros && . fishros

Operation flow:

1. Enter 1  -> Install ROS2
   ↓
2. Enter 2  -> Install without switching source (already done in Step 1)
   ↓
3. Enter 1  -> Install ROS2 Humble
   ↓
4. Enter 1  -> Install ROS2 Humble Desktop version

Installation options:

Option Included Size Recommendation
Desktop ROS2 + RViz + Gazebo + dev tools ~2GB ✅ Recommended
Base ROS2 core only ~500MB For server usage

Install process notes:

💡 During installation you may need to:
- Press Enter to continue
- Type Y to confirm installation
- Wait about 20-30 minutes (depends on network)

⚠️ Keep network stable during installation; do not interrupt.

✅ Completion sign: "ROS2 installation completed" or "Installation complete"

Step 3️⃣: Configure rosdep

Purpose: Configure ROS dependency manager for automatic package dependency installation.

Command:

wget http://fishros.com/install -O fishros && . fishros

Operation flow:

1. Enter 3  -> Configure rosdep
   ↓
2. Wait for configuration to finish
   ↓
3. Update rosdep manually

Update rosdep:

rosdepc update

✅ Completion sign: rosdepc update runs successfully without errors

Step 4️⃣: Update System Environment

Purpose: Configure ROS2 environment variables so ROS2 commands are available in terminal.

Command:

wget http://fishros.com/install -O fishros && . fishros

Operation flow:

Enter 4  -> Update system environment

Environment configuration details:

The script automatically appends this line to ~/.bashrc:

source /opt/ros/humble/setup.bash

Manual fallback:

If automatic configuration fails:

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

✅ Completion sign: ROS2 commands (e.g. ros2) work in a new terminal

✅ Step 5️⃣: Test Verification

Run demo_nodes

Test 1 - Publisher (Talker):

Open the first terminal and run:

ros2 run demo_nodes_cpp talker

Expected output:

[INFO] [talker]: Publishing: 'Hello World: 1'
[INFO] [talker]: Publishing: 'Hello World: 2'
[INFO] [talker]: Publishing: 'Hello World: 3'
...

Test 2 - Subscriber (Listener):

Open the second terminal and run:

ros2 run demo_nodes_cpp listener

Expected output:

[INFO] [listener]: I heard: [Hello World: 1]
[INFO] [listener]: I heard: [Hello World: 2]
[INFO] [listener]: I heard: [Hello World: 3]
...

Result criteria:

Behavior Result Notes
Talker publishes messages ✅ Publisher node works
Listener receives messages ✅ Subscriber node works
Message contents match ✅ Communication works

✅ If both nodes run and communicate correctly, ROS2 is working properly

Check RViz

Command:

rviz2

Expected result:

  • RViz window opens normally
  • 3D visualization interface is shown
  • Left-side display panel appears
  • No error prompts

RViz checklist:

Check item Normal status
Window opens ✅ Visible normally
Left panel ✅ Displays panel visible
Center viewport ✅ 3D view normal
Error state ✅ No red error messages

✅ If RViz launches correctly, desktop installation is successful

📊 Final Verification Checklist

After all tests, confirm:

  • [ ] ✅ ros2 --version shows a valid version
  • [ ] ✅ talker and listener communicate correctly
  • [ ] ✅ rviz2 starts normally
  • [ ] ✅ colcon and rosdep tools are available
  • [ ] ✅ ROS2 commands work in a newly opened terminal

If all above pass, congratulations, ROS2 Humble is installed successfully! 🎉

🔧 Common Troubleshooting

Issue 1: ros2 command not found

Symptom:

bash: ros2: command not found

Solution:

# Source environment manually
source /opt/ros/humble/setup.bash

# Persist in shell startup
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

Issue 2: rosdep update fails

Symptom:

ERROR: unable to process source ...

Solution:

# Reconfigure rosdep
sudo rm -rf /etc/ros/rosdep
wget http://fishros.com/install -O fishros && . fishros
# Select option 3 to configure rosdep

# Update again
rosdep update

Issue 3: demo_nodes package not found

Symptom:

Package 'demo_nodes_cpp' not found

Solution:

sudo apt update
sudo apt install ros-humble-demo-nodes-cpp ros-humble-demo-nodes-py