Registry /
devops / colcon-common-extensions
Install & Compatibility
Where this runs
tested against v0.3.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 49.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.2s · import 0.000s · 50MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
main
✓ import colcon_common_extensions
✗ from colcon_common_extensions import main
This quickstart demonstrates how to verify the installation of the 'colcon' command-line tool, which is enabled by `colcon-common-extensions`. It executes `colcon --version` using `subprocess` to confirm that the tool is accessible and functional within a Python environment.
import subprocess
import sys
# colcon-common-extensions itself is a meta-package and doesn't expose
# direct Python APIs for user applications. Its primary utility is installing
# the 'colcon' command-line tool and its extensions.
# This quickstart verifies the 'colcon' command is available and functional.
try:
# Using '-m colcon_core.cli' to run colcon as a module is generally more robust
# than 'colcon' directly, especially in isolated Python environments.
result = subprocess.run(
[sys.executable, "-m", "colcon_core.cli", "--version"],
capture_output=True,
text=True,
check=True
)
print(f"colcon command is available. Version:\n{result.stdout.strip()}")
print("colcon command is functional.")
except FileNotFoundError:
print("Error: 'colcon' executable not found. Ensure colcon-common-extensions is installed and in PATH.")
sys.exit(1)
except subprocess.CalledProcessError as e:
print(f"Error running colcon: {e}")
print(f"Stdout: {e.stdout}")
print(f"Stderr: {e.stderr}")
sys.exit(1)
colcon --version
Debug
Known issues
gotchacolcon-common-extensions is a meta-package and does not provide direct Python APIs for user code. Its primary purpose is to bundle 'colcon-core' and other 'colcon-*' extension packages, enabling the 'colcon' command-line interface with a full set of features.fixDo not attempt to import symbols directly from `colcon_common_extensions`. Instead, import from specific `colcon_*` packages (e.g., `colcon_core`) or use the `colcon` CLI.
affects: All versions
gotchaThe `colcon` build system is primarily designed for ROS 2 development workflows. While it can be used for other C++/Python projects, its default behaviors and assumptions (e.g., package discovery, environment hooks) are heavily optimized for the ROS 2 ecosystem. Using it outside of ROS 2 might require significant custom configuration.fixWhen using `colcon` outside of ROS 2, review the documentation for `colcon-core` and its extensions carefully, particularly regarding package discovery, build types, and environment setup.
affects: All versions
gotchaProper functioning of `colcon` (especially for finding ROS 2 packages and dependencies) often depends on sourcing ROS 2 environment setup scripts (e.g., `source /opt/ros/humble/setup.bash`). Forgetting to do so will result in `colcon` not finding ROS 2 packages or build dependencies.fixAlways `source` the appropriate ROS 2 `setup.bash`/`setup.zsh`/`setup.ps1` before running `colcon` commands. For custom workspaces, remember to source the workspace's `install/setup.bash` after building.
affects: All versions (when used with ROS 2)
breaking`colcon` and its extensions (including those pulled by `colcon-common-extensions`) are strictly Python 3 compatible. Attempts to install or run `colcon` in a Python 2 environment will result in errors.fixEnsure you are using Python 3 (preferably Python 3.8+ as per ROS 2 recommendations). Use `python3 -m pip install ...` or a virtual environment configured for Python 3.
affects: < 0.1.0
Upgrade
Version history
0.3.0latest on PyPI · released Aug 31, 2022
Audit
Dependencies
colcon-corerequiredThis meta-package directly pulls in colcon-core and numerous other colcon-* extensions (e.g., colcon-ros, colcon-cmake, colcon-bash, etc.) as its primary function to provide a complete colcon environment.