{"id":9606,"library":"colcon-parallel-executor","title":"Colcon Parallel Executor","description":"colcon-parallel-executor is an extension for the colcon build tool, primarily used within the ROS ecosystem, to enable efficient parallel processing of packages during build, test, and install operations. It aims to maximize throughput by building independent packages concurrently. The current version is 0.4.0. Releases are typically tied to updates in the colcon ecosystem or bug fixes.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-parallel-executor/","tags":["colcon","ROS","robotics","build-system","parallel-processing","extension"],"install":[{"cmd":"pip install colcon-parallel-executor","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This library is an extension for colcon and requires colcon-core to be installed to function, though it's not a direct Python dependency but a runtime/functional one.","package":"colcon-core","optional":false}],"imports":[],"quickstart":{"code":"colcon build --executor parallel","lang":"bash","description":"To use the parallel executor, simply pass `--executor parallel` to your colcon command. This will instruct colcon to use this extension to build packages in parallel where possible based on their dependencies. Ensure `colcon-parallel-executor` is installed in the same environment as `colcon`."},"warnings":[{"fix":"Uninstall `colcon-concurrent-executor` and install `colcon-parallel-executor`. Update any scripts to use `--executor parallel` instead of `--executor concurrent`.","message":"The `colcon-parallel-executor` package supersedes and replaces the older `colcon-concurrent-executor`. If you were previously using `colcon-concurrent-executor`, you should switch to `colcon-parallel-executor` for continued support and improvements.","severity":"deprecated","affected_versions":"<0.4.0"},{"fix":"Always explicitly specify `--executor parallel` if you need to guarantee parallel execution across different `colcon-core` versions or environments. Otherwise, confirm your `colcon-core` default behavior.","message":"Recent versions of `colcon-core` (e.g., >=0.10.0) often use the `parallel` executor as the default for many build verbs. Explicitly specifying `--executor parallel` might be redundant but harmless in such cases. However, for older `colcon-core` versions, it is necessary to explicitly enable it.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `package.xml` or equivalent dependency declarations are accurate. If experiencing hangs or unexpected failures, try reducing parallelism (e.g., `--parallel-workers 1`) to debug, or consult package maintainers for parallelization best practices.","message":"Using a parallel executor can expose race conditions, deadlocks, or resource contention issues if package dependencies are not correctly defined or if underlying build processes are not parallelization-safe (e.g., writing to shared non-thread-safe resources).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure the package is installed: `pip install colcon-parallel-executor`. If using virtual environments, activate the correct environment before running `colcon`.","cause":"The `colcon-parallel-executor` package is not installed in the Python environment where `colcon` is being run, or `colcon` cannot find its entry point.","error":"colcon: error: unrecognized arguments: --executor parallel"},{"fix":"Try reducing the number of parallel workers (`colcon build --executor parallel --parallel-workers 2`). Monitor system resources (CPU, RAM). Review the logs of the last package that started building to identify potential issues or long-running tasks. Ensure package dependencies are correctly defined.","cause":"This can indicate a deadlock between parallel build jobs, resource exhaustion (e.g., too many processes for available RAM/CPU), or a single build step that is inherently sequential and very long-running, giving the appearance of a hang.","error":"Build process appears to hang indefinitely or shows no progress during parallel execution."},{"fix":"Upgrade both `colcon-core` and `colcon-parallel-executor` to their latest compatible versions: `pip install --upgrade colcon-core colcon-parallel-executor`. If the issue persists, report it to the `colcon-parallel-executor` GitHub repository.","cause":"This specific error (or similar `AttributeError`s related to internal executor logic) can sometimes occur due to an incompatibility between the installed `colcon-core` version and `colcon-parallel-executor`, indicating an API change was not handled.","error":"RuntimeError: 'NoneType' object has no attribute 'add_job'"}]}