Documentation Version

You're reading the documentation for an older, but still supported, version of MoveIt 2. For information on the recommended stable version, please have a look at Humble.

Getting Started

This tutorial will install MoveIt 2 and create a workspace sandbox to run the tutorials and example robot.

Install ROS 2 and Colcon

Install ROS 2 Galactic. It is easy to miss steps when going through the ROS 2 installation tutorial. If you run into errors in the next few steps, a good place to start is to go back and make sure you have installed ROS 2 correctly. One that users commonly forget is to source the ROS 2 install itself.

source /opt/ros/galactic/setup.bash


Unlike ROS 1 setup scripts, in ROS 2 the setup scripts do not attempt to switch what version of ROS you are using. This means that if you have previously sourced a different version of ROS, including from within your .bashrc file, you will run into errors during the building step. To fix this change what is sourced in your .bashrc and start a new terminal.

Install rosdep to install system dependencies :

sudo apt install python3-rosdep

Once you have ROS 2 installed, make sure you have the most up to date packages:

sudo rosdep init
rosdep update
sudo apt update
sudo apt dist-upgrade

Install Colcon the ROS 2 build system with mixin:

sudo apt install python3-colcon-common-extensions
sudo apt install python3-colcon-mixin
colcon mixin add default
colcon mixin update default

Install vcstool :

sudo apt install python3-vcstool

Create A Colcon Workspace and Download Tutorials

For tutorials you will need to have a colcon workspace setup.

mkdir -p ~/ws_moveit2/src

Download MoveIt 2 Tutorials Source

Move into your colcon workspace and pull the MoveIt 2 tutorials source:

cd ~/ws_moveit2/src
git clone -b galactic --depth 1
vcs import < moveit2_tutorials/moveit2_tutorials.repos

The import command may ask for your GitHub credentials. You can just press Enter until it moves on (ignore the “Authentication failed” error).

Build your Colcon Workspace

The following will install from Debian any package dependencies not already in your workspace. This is the step that will install MoveIt and all of its dependencies:

sudo apt update && rosdep install -r --from-paths . --ignore-src --rosdistro $ROS_DISTRO -y

The next command will configure your colcon workspace:

cd ~/ws_moveit2
colcon build --mixin release

Source the colcon workspace:

source ~/ws_moveit2/install/setup.bash

Optional: add the previous command to your .bashrc:

echo 'source ~/ws_moveit2/install/setup.bash' >> ~/.bashrc


Sourcing the setup.bash automatically in your ~/.bashrc is not required and often skipped by advanced users who use more than one colcon workspace at a time, but we recommend it for simplicity.