colcon-ros

0.5.0 · active · verified Fri Apr 17

colcon-ros is an extension for the colcon build tool that adds support for discovering and building ROS packages (both ROS 1 and ROS 2 style, primarily ROS 2). It enables `colcon` to understand `package.xml` files, making it the standard build system for ROS 2. The current version is 0.5.0, and it follows the release cadence of the wider colcon and ROS 2 ecosystem, with updates often tied to new ROS distributions.

Common errors

```
colcon: command not found
```
cause The `colcon-core` package, which provides the `colcon` executable, is not installed or not in your system's PATH.

fix Install `colcon-core` by running `pip install colcon-core` or ensure your ROS 2 environment (which typically includes colcon) is properly sourced.
```
--- stderr: <package_name>
Package '<package_name>' not found
```
cause colcon-ros could not find a `package.xml` in the expected directory, or the package directory is not within a recognized colcon workspace `src` directory.

fix Verify that your ROS package contains a `package.xml` file at its root. Ensure the package is located directly within the `src` folder of your colcon workspace, and that you are running `colcon build` from the workspace root.
```
ModuleNotFoundError: No module named 'rclpy'
```
cause You are trying to run a ROS 2 Python node or script, but the ROS 2 environment (including its Python packages) has not been sourced or is not correctly set up in your current shell.

fix Navigate to your ROS 2 workspace root (`~/ros2_ws`) and run `source install/setup.bash` (or `setup.zsh`, `setup.ps1`) before attempting to run ROS 2 commands or Python scripts.
```
could not find a version that satisfies the requirement colcon-core>=x.y.z
```
cause When installing `colcon-ros` with `pip`, a conflict in Python environments or available `colcon-core` versions is preventing the dependency from being resolved.

fix Ensure you are using a Python 3 environment. Try updating pip (`pip install --upgrade pip`) and then installing `colcon-core` first, followed by `colcon-ros`: `pip install colcon-core && pip install colcon-ros`. If using a ROS distribution, prefer installing `colcon-common-extensions` via `apt` or `rosdep`.

Warnings

gotcha colcon-ros is an extension and requires `colcon-core` to be installed and accessible. Installing only `colcon-ros` via `pip` typically pulls in `colcon-core` as a dependency, but direct `colcon-core` installation is also common, especially when installed via ROS 2 distribution packages (`apt`).
Fix: Ensure `colcon-core` is installed (`pip install colcon-core` or via ROS distribution packages like `ros-foxy-colcon-common-extensions`). Verify `colcon --version` works.
gotcha `colcon-ros` discovers ROS packages based on the presence of a `package.xml` file within a directory. If a directory contains source code but no `package.xml`, `colcon-ros` will ignore it.
Fix: For `colcon` to recognize a directory as a ROS package, ensure it contains a valid `package.xml` file at its root. Use `ros2 pkg create` for new packages to generate this file automatically.
gotcha After building a workspace with `colcon build`, the generated setup scripts (e.g., `install/setup.bash`) *must* be sourced in each new terminal session where you intend to use the built packages. Failing to do so will result in 'command not found' or 'package not found' errors for ROS 2 executables or libraries.
Fix: Always execute `source install/setup.bash` (or `setup.zsh`, `setup.ps1`) from your workspace root after building and in any new shell where you need to use the workspace contents.
gotcha Mixing ROS 1 and ROS 2 environment setups (e.g., sourcing `setup.bash` from a ROS 1 distro and then a ROS 2 workspace) can lead to PATH and library conflicts, especially concerning Python versions and build tools. `colcon-ros` is primarily for Python 3 and ROS 2.
Fix: Always use separate terminal sessions for ROS 1 and ROS 2 development. For ROS 2, ensure your environment points to Python 3 and avoid sourcing ROS 1 setup files in the same shell.

Install

pip install colcon-ros Install via pip

Quickstart

This quickstart demonstrates how to set up a basic ROS 2 workspace and build a package using `colcon build`, which leverages `colcon-ros` to discover and process ROS-specific package information. The resulting setup files must be sourced to make the built packages available in your environment.

# 1. Create a ROS 2 workspace directory
mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src

# 2. Clone a sample ROS 2 package (e.g., example_interfaces)
git clone https://github.com/ros2/example_interfaces.git

# 3. Navigate back to the workspace root
cd ~/ros2_ws

# 4. Build the workspace using colcon-ros
# colcon-ros integrates seamlessly with `colcon build` to find ROS packages
colcon build

# 5. Source the workspace setup file to make built packages available
# (This needs to be done in every new terminal session)
source install/setup.bash

# 6. Verify a built package is available (e.g., check for an executable)
# For example_interfaces, there might not be a direct executable, 
# but you can check if it's in the AMENT_PREFIX_PATH
# echo $AMENT_PREFIX_PATH

view raw JSON →