Installing ROS 2 and Colcon for MoveIt 2
MoveIt 2 works with multiple versions of ROS 2, and the installation process can feel overwhelming if you’re new. This guide breaks it down step by step in a way that’s easier to follow.
Recommended Setup
MoveIt 2 supports several ROS 2 versions. Here are the key options:
-
Rolling Ridley – Rolling development release
-
Jazzy Jalisco – Latest LTS release (May 2024)
-
Humble Hawksbill – Supported LTS release (May 2022)
👉 If you’re just starting out, the recommended path is Ubuntu 24.04 with ROS 2 Jazzy (latest stable LTS).
Step 1: Source Your ROS 2 Installation
One of the most common mistakes is forgetting to source your ROS installation. Run the following command (adjust if you installed a different version):
source /opt/ros/jazzy/setup.bash
⚠️ Important: Unlike ROS 1, ROS 2 does not auto-switch between versions. If your .bashrc is sourcing an older ROS version, it will cause build errors. Make sure your .bashrc points to the correct version and restart your terminal.
Step 2: Install rosdep
rosdep is used to install system dependencies.
sudo apt install python3-rosdep
sudo rosdep init
rosdep update
sudo apt update
sudo apt dist-upgrade
Step 3: Install Colcon
Colcon is the official build tool for ROS 2. Install it along with mixins:
sudo apt install python3-colcon-common-extensions
sudo apt install python3-colcon-mixin
colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
colcon mixin update default
Step 4: Install vcstool
sudo apt install python3-vcstool
Step 5: Create a Colcon Workspace
mkdir -p ~/ws_moveit/src
Step 6: Download MoveIt Tutorials
Move into your workspace and clone the tutorials (replace <branch> with humble, jazzy, or main):
cd ~/ws_moveit/src
git clone -b <branch> https://github.com/moveit/moveit2_tutorials
Now fetch the rest of MoveIt source code:
vcs import --recursive < moveit2_tutorials/moveit2_tutorials.repos
If GitHub asks for credentials, just press Enter. Ignore the “Authentication failed” warnings.
Step 7: Build Your Workspace
First, remove any old MoveIt binaries:
sudo apt remove ros-$ROS_DISTRO-moveit*
Install missing dependencies:
sudo apt update && rosdep install -r --from-paths . --ignore-src --rosdistro $ROS_DISTRO -y
Build the workspace:
cd ~/ws_moveit
colcon build --mixin release
⏳ Note: This build may take 20+ minutes. A machine with 32 GB RAM is recommended.
Low Memory Systems
If your build fails due to RAM usage, try:
-
Build one package at a time:
colcon build --executor sequential -
Limit parallel workers:
colcon build --parallel-workers 4 -
For very limited systems:
MAKEFLAGS="-j4 -l1" colcon build --executor sequential
At the end, you should see:
Summary: X packages finished
Step 8: Source Your Workspace
source ~/ws_moveit/install/setup.bash
(Optional) Add it to your .bashrc so it’s automatically sourced every time:
echo 'source ~/ws_moveit/install/setup.bash' >> ~/.bashrc
✅ That’s it! You now have ROS 2, Colcon, and MoveIt 2 tutorials ready to go.