Registry / devops / colcon-core

colcon-core

JSON →
library0.21.0pypypi✓ verified 87d ago

colcon-core is the foundational Python package for 'colcon', a command-line tool designed to streamline the workflow of building, testing, and using multiple software packages, especially within robotics frameworks like ROS. It automates package discovery, dependency resolution, and environment setup. The library is currently at version 0.20.1 and follows a continuous release model, with new versions typically released as needed to support updates in related projects like ROS.

pip install colcon-core
INSTALL
IMPORT
SIG · COLCON-CORE
C
colcon-core
devopspythonv0.21.0
Install
6.2s avg
Import
113ms
Disk
53MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.21.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.119s · 49.2MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 6.2s · import 0.108s · 50MB
53MB installed
● package 53MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PackageIdentificationExtensionPoint
from colcon_core.package_identification import PackageIdentificationExtensionPoint
Common import for creating colcon package identification extensions.
EnvironmentExtensionPoint
from colcon_core.environment import EnvironmentExtensionPoint
Used for extending colcon's environment setup capabilities.
satisfies_version
from colcon_core.plugin_system import satisfies_version
Utility to check compatibility with colcon's plugin system versions.

This quickstart demonstrates how to create a minimal colcon workspace with a Python package, build it, and then prepare to run an executable defined within it. This example implicitly uses 'ament_python' build type, common in ROS environments. It creates the necessary directory structure and `setup.py`/`package.xml` files for `colcon` to discover and build the package.

import os # Create a dummy workspace and a simple Python package os.makedirs('my_workspace/src/my_python_package', exist_ok=True) with open('my_workspace/src/my_python_package/setup.py', 'w') as f: f.write(""" from setuptools import setup package_name = 'my_python_package' setup( name=package_name, version='0.0.0', packages=[package_name], data_files=[ ('share/ament_index/resource_index/packages', ['resource/' + package_name]), ('share/' + package_name, ['package.xml']) ], install_requires=['setuptools'], zip_safe=True, maintainer='Your Name', maintainer_email='you@example.com', description='A minimal Python package for colcon', license='Apache-2.0', tests_require=['pytest'], entry_points={ 'console_scripts': [ 'my_node = my_python_package.main:main' ], }, ) """) with open('my_workspace/src/my_python_package/package.xml', 'w') as f: f.write(""" <?xml version="1.0"?> <?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?> <package format="3"> <name>my_python_package</name> <version>0.0.0</version> <description>TODO: Package description</description> <maintainer email="you@example.com">Your Name</maintainer> <license>Apache-2.0</license> <test_depend>ament_copyright</test_depend> <test_depend>ament_flake8</test_depend> <test_depend>ament_pep257</test_depend> <test_depend>python3-pytest</test_depend> <export> <build_type>ament_python</build_type> </export> </package> """) with open('my_workspace/src/my_python_package/my_python_package/main.py', 'w') as f: f.write(""" def main(): print('Hello from my_python_package!') if __name__ == '__main__': main() """) os.makedirs('my_workspace/src/my_python_package/resource', exist_ok=True) with open('my_workspace/src/my_python_package/resource/my_python_package', 'w') as f: f.write('') # Now, build the workspace using colcon print('\n--- Running colcon build ---') os.system('cd my_workspace && colcon build --packages-select my_python_package') # Source the setup file and run the node print('\n--- Sourcing setup and running node ---') # For simplicity, we'll try to run directly if possible, or instruct sourcing. # In a real shell, you would run: . install/setup.bash (or .ps1, .bat) # For a self-contained python script, it's complex to source a shell file. # Instead, we will try to invoke the installed script directly if available node_path = 'my_workspace/install/my_python_package/lib/my_python_package/my_node' if os.path.exists(node_path): os.system(node_path) else: print("To run the node: cd my_workspace && . install/setup.bash && my_node")
colcon --version
Debug
Known issues
breakingIncompatibility with `empy` version 4.0 and higher due to breaking API changes in `empy`. This can lead to `ImportError: cannot import name 'OVERRIDE_OPT' from 'em'` or similar failures.
fix
Downgrade `empy` to a compatible version, typically `empy==3.3.4`, or ensure `colcon-core` is updated to a version that explicitly pins a compatible `empy` version.
affects: colcon-core <= 0.19.x (reported November 2023, fixed in subsequent releases by pinning `empy` dependency)
breaking`colcon-core` versions from `0.13.1` introduced a dependency on Python 3.8's `importlib.metadata` or the `importlib-metadata` backport. This broke installations via `apt` on older Ubuntu versions (e.g., 18.04 with Python 3.6) which lacked these packages, resulting in 'unmet dependencies' errors.
fix
For Python < 3.8, install `colcon-core` using `pip` to automatically get the `importlib-metadata` backport, or remain on `colcon-core` versions `0.14.0` or earlier if using `apt` on unsupported Python versions. Alternatively, upgrade your Python environment to 3.8 or newer.
affects: colcon-core 0.13.1 and later versions (affecting Python < 3.8 installations via `apt`)
gotchaWhen using `--symlink-install`, `colcon-core` may be incompatible with `setuptools >= 80.0`, leading to build failures or incorrect installations.
fix
Downgrade `setuptools` to a version older than `80.0` if you encounter issues with `--symlink-install`. Check `colcon-core`'s GitHub for updates on `setuptools` compatibility.
affects: colcon-core versions prior to explicit fix (reported March 2026)
gotcha`colcon build` might use an unexpected Python interpreter if not explicitly invoked from within an activated virtual environment, particularly on Windows, causing `ModuleNotFoundError` for packages expected to be in the virtual environment.
fix
Explicitly invoke `colcon` using the desired Python interpreter (e.g., `python3 -m colcon build ...`) or ensure all `colcon` packages and their dependencies are installed directly into the target virtual environment.
affects: All versions
Errors
Common errors & fixes
ERROR:colcon.colcon_core* is declared multiple times
This error typically occurs when `colcon-core` and an extension package (like `colcon-override-check`, implicitly installed by `colcon-common-extensions`) both attempt to provide the same functionality or argument, often due to version mismatch or the functionality being refactored into a separate package.
fix
Ensure all `colcon` related packages (e.g., `colcon-core`, `colcon-common-extensions`, `colcon-override-check`) are up-to-date. If installed via `apt`, run `sudo apt update && sudo apt upgrade`. If via `pip`, try `pip install --upgrade --upgrade-strategy eager colcon-common-extensions`.
ImportError: cannot import name 'OVERRIDE_OPT' from 'em'
`colcon-core` depends on `empy` for templating, but `empy 4.0` introduced breaking changes, removing `OVERRIDE_OPT`.
fix
Install a compatible version of `empy`. The fix is usually `pip install 'empy<4'` or specifically `pip install empy==3.3.4`.
E: Unable to correct problems, you have held broken packages. The following packages have unmet dependencies: python3-colcon-core : Depends: python3 (>= 3.8) but 3.6.7-1~18.04 is to be installed or python3-importlib-metadata but it is not installable
`colcon-core` version 0.13.1 and newer requires Python 3.8+ or the `importlib-metadata` backport, which is not available via `apt` on older Ubuntu distributions (e.g., 18.04 with Python 3.6).
fix
Install `colcon-core` and its extensions via `pip` (e.g., `pip install colcon-common-extensions`) instead of `apt` on affected systems, as `pip` will automatically install the `importlib-metadata` backport. Alternatively, upgrade your operating system and Python version to 3.8 or newer.
Upgrade
Version history
0.21.0latest on PyPI · released Jun 1, 2026
Audit
Dependencies
empyrequiredTemplating engine used by various build types; specific versions might cause conflicts.
setuptoolsrequiredUsed for Python package identification and building; specific versions can cause incompatibilities with --symlink-install.
importlib-metadataoptionalBackport for Python < 3.8; required for package metadata discovery on older Python versions.
Agent activity
36 hits · last 30 days
node
34
OpenAI (training)
1
Resources
colcon-core — pip install colcon-core · libregistry