{"id":7096,"library":"colcon-core","title":"colcon-core","description":"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.","status":"active","version":"0.20.1","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-core/","tags":["build-tool","ROS","robotics","workspace","package-management","CLI"],"install":[{"cmd":"pip install colcon-core","lang":"bash","label":"Basic installation via pip"},{"cmd":"pip install colcon-common-extensions","lang":"bash","label":"Recommended for common build types (installs colcon-core and extensions)"}],"dependencies":[{"reason":"Templating engine used by various build types; specific versions might cause conflicts.","package":"empy","optional":false},{"reason":"Used for Python package identification and building; specific versions can cause incompatibilities with --symlink-install.","package":"setuptools","optional":false},{"reason":"Backport for Python < 3.8; required for package metadata discovery on older Python versions.","package":"importlib-metadata","optional":true}],"imports":[{"note":"Common import for creating colcon package identification extensions.","symbol":"PackageIdentificationExtensionPoint","correct":"from colcon_core.package_identification import PackageIdentificationExtensionPoint"},{"note":"Used for extending colcon's environment setup capabilities.","symbol":"EnvironmentExtensionPoint","correct":"from colcon_core.environment import EnvironmentExtensionPoint"},{"note":"Utility to check compatibility with colcon's plugin system versions.","symbol":"satisfies_version","correct":"from colcon_core.plugin_system import satisfies_version"}],"quickstart":{"code":"import os\n\n# Create a dummy workspace and a simple Python package\nos.makedirs('my_workspace/src/my_python_package', exist_ok=True)\n\nwith open('my_workspace/src/my_python_package/setup.py', 'w') as f:\n    f.write(\"\"\"\nfrom setuptools import setup\n\npackage_name = 'my_python_package'\n\nsetup(\n    name=package_name,\n    version='0.0.0',\n    packages=[package_name],\n    data_files=[\n        ('share/ament_index/resource_index/packages', ['resource/' + package_name]),\n        ('share/' + package_name, ['package.xml'])\n    ],\n    install_requires=['setuptools'],\n    zip_safe=True,\n    maintainer='Your Name',\n    maintainer_email='you@example.com',\n    description='A minimal Python package for colcon',\n    license='Apache-2.0',\n    tests_require=['pytest'],\n    entry_points={\n        'console_scripts': [\n            'my_node = my_python_package.main:main'\n        ],\n    },\n)\n\"\"\")\n\nwith open('my_workspace/src/my_python_package/package.xml', 'w') as f:\n    f.write(\"\"\"\n<?xml version=\"1.0\"?>\n<?xml-model href=\"http://download.ros.org/schema/package_format3.xsd\" schematypens=\"http://www.w3.org/2001/XMLSchema\"?>\n<package format=\"3\">\n  <name>my_python_package</name>\n  <version>0.0.0</version>\n  <description>TODO: Package description</description>\n  <maintainer email=\"you@example.com\">Your Name</maintainer>\n  <license>Apache-2.0</license>\n\n  <test_depend>ament_copyright</test_depend>\n  <test_depend>ament_flake8</test_depend>\n  <test_depend>ament_pep257</test_depend>\n  <test_depend>python3-pytest</test_depend>\n\n  <export>\n    <build_type>ament_python</build_type>\n  </export>\n</package>\n\"\"\")\n\nwith open('my_workspace/src/my_python_package/my_python_package/main.py', 'w') as f:\n    f.write(\"\"\"\ndef main():\n    print('Hello from my_python_package!')\n\nif __name__ == '__main__':\n    main()\n\"\"\")\n\nos.makedirs('my_workspace/src/my_python_package/resource', exist_ok=True)\nwith open('my_workspace/src/my_python_package/resource/my_python_package', 'w') as f:\n    f.write('')\n\n# Now, build the workspace using colcon\nprint('\\n--- Running colcon build ---')\nos.system('cd my_workspace && colcon build --packages-select my_python_package')\n\n# Source the setup file and run the node\nprint('\\n--- Sourcing setup and running node ---')\n# For simplicity, we'll try to run directly if possible, or instruct sourcing.\n# In a real shell, you would run: . install/setup.bash (or .ps1, .bat)\n# For a self-contained python script, it's complex to source a shell file.\n# Instead, we will try to invoke the installed script directly if available\nnode_path = 'my_workspace/install/my_python_package/lib/my_python_package/my_node'\nif os.path.exists(node_path):\n    os.system(node_path)\nelse:\n    print(\"To run the node: cd my_workspace && . install/setup.bash && my_node\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"Incompatibility 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.","severity":"breaking","affected_versions":"colcon-core <= 0.19.x (reported November 2023, fixed in subsequent releases by pinning `empy` dependency)"},{"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.","message":"`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.","severity":"breaking","affected_versions":"colcon-core 0.13.1 and later versions (affecting Python < 3.8 installations via `apt`)"},{"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.","message":"When using `--symlink-install`, `colcon-core` may be incompatible with `setuptools >= 80.0`, leading to build failures or incorrect installations.","severity":"gotcha","affected_versions":"colcon-core versions prior to explicit fix (reported March 2026)"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"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.","error":"ERROR:colcon.colcon_core* is declared multiple times"},{"fix":"Install a compatible version of `empy`. The fix is usually `pip install 'empy<4'` or specifically `pip install empy==3.3.4`.","cause":"`colcon-core` depends on `empy` for templating, but `empy 4.0` introduced breaking changes, removing `OVERRIDE_OPT`.","error":"ImportError: cannot import name 'OVERRIDE_OPT' from 'em'"},{"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.","cause":"`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).","error":"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"}]}