colcon-ros

library0.5.0pypypiunverified

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.

devops

pip install colcon-ros

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · COLCON-ROS

colcon-ros

devopspythonv0.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

colcon --version

Debug

Known issues

gotchacolcon-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.

affects: All versions

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.

affects: All versions

gotchaAfter 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.

affects: All versions

gotchaMixing 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.

affects: All versions

Errors

Common errors & fixes

colcon: command not found

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

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'

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

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`.

Upgrade

Version history

0.5.0latest on PyPI · released Jun 24, 2024

Audit

Dependencies

colcon-corerequiredProvides the core `colcon` command-line tool that `colcon-ros` extends.

colcon-package-informationrequiredUsed by `colcon-ros` for processing package metadata.

rosdistrorequiredRequired for resolving ROS distribution-specific information.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/colcon/colcon-ros ↗

packagehttps://pypi.org/project/colcon-ros/ ↗

homepagehttps://colcon.readthedocs.io ↗

changeloghttps://github.com/colcon/colcon-ros/milestones?direction=desc&sort=due_date&state=closed ↗