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
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.119s · 49.2MB
glibcpy 3.10–3.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.fixDowngrade `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.fixFor 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.fixDowngrade `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.fixExplicitly 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.
fixEnsure 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`.
fixInstall 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).
fixInstall `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.