{"id":8902,"library":"colcon-notification","title":"colcon-notification","description":"colcon-notification is an extension for the `colcon` meta build tool, primarily used within the Robot Operating System (ROS) ecosystem, to provide status notifications. It enables desktop notifications and updates a status line in the terminal title during `colcon` invocations like `build` or `test`. The current version is 0.3.1, and it maintains an active development and release cadence in line with the broader `colcon` and ROS projects.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-notification/","tags":["build-tool","ros","notifications","cli-extension","colcon"],"install":[{"cmd":"pip install colcon-notification","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"This library is an extension for colcon-core.","package":"colcon-core","optional":false},{"reason":"Provides desktop notification API functionality on Linux systems.","package":"notify2","optional":true}],"imports":[{"note":"colcon-notification is an extension, not typically imported directly into user Python scripts. Its functionality is enabled via colcon command-line arguments or configuration as an event handler.","symbol":"Extension functionality","correct":"colcon build --event-handlers desktop_notification+"}],"quickstart":{"code":"# This is not a Python import, but how to use the notification feature through colcon CLI.\n# To build a workspace and enable desktop notifications:\nmkdir -p ~/my_ros2_ws/src\ncd ~/my_ros2_ws\n# Populate src/ with colcon-compatible packages (e.g., ROS 2 examples)\n# git clone https://github.com/ros2/examples src/examples\n\n# Build with desktop notifications enabled\ncolcon build --event-handlers desktop_notification+\n\n# Or to only show a status line in the terminal title\ncolcon build --event-handlers status+","lang":"bash","description":"colcon-notification provides event handlers for the `colcon` command-line tool. To use its features, you typically invoke `colcon` with specific `--event-handlers` arguments. `desktop_notification+` enables desktop pop-up notifications, while `status+` shows a continuously updating status line in your terminal title."},"warnings":[{"fix":"Update your environment variables or scripts to use `COLCON_EXTENSION_BLOCKLIST`.","message":"The environment variable to blacklist/block extensions was renamed from `COLCON_EXTENSION_BLACKLIST` to `COLCON_EXTENSION_BLOCKLIST`.","severity":"breaking","affected_versions":"<= 0.2.19 (before July 2022)"},{"fix":"To disable desktop notifications for a single invocation, use `colcon <verb> --event-handlers desktop_notification-`. To disable them system-wide, set the environment variable `COLCON_EXTENSION_BLOCKLIST=colcon_core.event_handler.desktop_notification`.","message":"Desktop notifications can be intrusive and are often enabled by default. Users frequently want to disable them.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your D-Bus system is properly configured and accessible for desktop notifications. If issues persist, consider disabling desktop notifications using the `--event-handlers desktop_notification-` flag or `COLCON_EXTENSION_BLOCKLIST` environment variable.","message":"On some Linux desktop environments (e.g., Pop OS + Regolith), desktop notifications might fail with D-Bus related errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"This issue has been addressed in recent versions. If encountered with older installations, a workaround was to manually rename the `colcon_terminal_notifier.app` to `colcon-terminal-notifier.app` or modify `terminal_notifier.py`.","message":"On macOS, older versions had an issue with the `terminal-notifier.app` path due to a mismatch in naming conventions (underscore vs. dash).","severity":"gotcha","affected_versions":"<= 0.2.19"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Update `colcon-notification` to a newer version (post-0.2.19) where this was resolved. If updating is not an option, manually verify and correct the application name in the install prefix or in the `terminal_notifier.py` file.","cause":"Mismatch in the application name (colcon_terminal_notifier.app vs colcon-terminal-notifier.app) for the macOS notification tool, typically on older versions or specific build setups.","error":"ERROR：Could not find the colcon-terminal-notifier.app in the install prefix '/usr/local"},{"fix":"Check your desktop environment's D-Bus setup and notification service. If the issue persists, disable desktop notifications for `colcon` using `colcon <verb> --event-handlers desktop_notification-` or set `COLCON_EXTENSION_BLOCKLIST=colcon_core.event_handler.desktop_notification`.","cause":"The `notify2` backend (used for desktop notifications on Linux) failed to connect or send a message via the D-Bus message bus, often due to a misconfigured desktop environment or D-Bus service.","error":"Exception in desktop notification extension 'notify2':org.freedesktop.DBus.Error.NoReply: Message recipient disconnected from message bus without replying."},{"fix":"Disable them per invocation with `colcon <verb> --event-handlers desktop_notification-`. For a system-wide disable, set the environment variable `COLCON_EXTENSION_BLOCKLIST=colcon_core.event_handler.desktop_notification`.","cause":"Desktop notifications are enabled by default through the `desktop_notification` event handler within colcon-notification.","error":"Unwanted or annoying desktop notifications pop up during colcon builds."}]}