Installation

The functionality of colcon is split over multiple Python packages. The package colcon-core provides the command line tool colcon itself as well as few fundamental extensions. Additional functionality is provided by separate packages, e.g. colcon-cmake adds support for packages which use CMake. The following instructions install a set of common colcon packages.

Using Debian packages

On platforms which support Debian packages using those is preferred since they will be updated using apt together with other system packages.

The Debian packages are currently hosted in apt repositories from the ROS project. You can choose either of the two following apt repositories.

  • ROS 1 repository

    $ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu `lsb_release -cs` main" > /etc/apt/sources.list.d/ros-latest.list'
    $ sudo apt-key adv --keyserver ha.pool.sks-keyservers.net --recv-keys 421C365BD9FF1F717815A3895523BAEEB01FA116
    
  • ROS 2 repository

    $ sudo sh -c 'echo "deb [arch=amd64,arm64] http://repo.ros2.org/ubuntu/main `lsb_release -cs` main" > /etc/apt/sources.list.d/ros2-latest.list'
    $ curl http://repo.ros2.org/repos.key | sudo apt-key add -
    

After that you can install the Debian package which depends on colcon-core as well as commonly used extension packages (see setup.cfg).

$ sudo apt update
$ sudo apt install python3-colcon-common-extensions

Using pip on any platform

On all non-Debian platforms the most common way of installation is the Python package manager pip. The following assumes that you are using a virtual environment with Python 3.5 or higher. If you want to install the packages globally it might be necessary to invoke pip3 instead of pip and require sudo.

$ pip install -U colcon-common-extensions

Note

The package colcon-common-extensions doesn’t contain any functionality itself but only depends on a set of other packages (see setup.cfg).

Note

You can find a list of released packages on PyPI using the keyword colcon.

Installing from source

Note

This approach is commonly only used by advanced users.

Commonly this is the case when you want to try or leverage new features or bug fixes which have been committed already but are not available in a released version yet. In order to use the latest state of any of the above packages you can invoke pip with a URL of the GitHub repository:

$ pip install -U git+https://github.com/colcon/colcon-common-extensions.git

Building from source

Since this is not a common use case for users you will find the documentation in the developer section.

Enable completion

Bash / zsh

On Linux / macOS the above instructions install the package colcon-argcomplete which offers command completion for bash and bash-like shells. To enable this feature you need to source the shell-specific script provided by that package. These scripts are named colcon-argcomplete.bash / colcon-argcomplete.zsh. For convenience you might want to source the one matching your shell in the user configuration, e.g. ~/.bashrc:

Depending on which instructions you followed to install the packages the location will vary:

  • Debian package: /usr/share/colcon-argcomplete/hook
  • PIP - user specific: $HOME/.local/share/colcon-argcomplete/hook
  • PIP - global: /usr/local/share/colcon-argcomplete/hook