Install & Compatibility
Where this runs
tested against v0.3.1 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.000s · 37.6MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 5.1s · import 0.000s · 38MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Extension functionality
✓ colcon build --event-handlers desktop_notification+
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.
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.
# This is not a Python import, but how to use the notification feature through colcon CLI.
# To build a workspace and enable desktop notifications:
mkdir -p ~/my_ros2_ws/src
cd ~/my_ros2_ws
# Populate src/ with colcon-compatible packages (e.g., ROS 2 examples)
# git clone https://github.com/ros2/examples src/examples
# Build with desktop notifications enabled
colcon build --event-handlers desktop_notification+
# Or to only show a status line in the terminal title
colcon build --event-handlers status+
Debug
Known issues
breakingThe environment variable to blacklist/block extensions was renamed from `COLCON_EXTENSION_BLACKLIST` to `COLCON_EXTENSION_BLOCKLIST`.fixUpdate your environment variables or scripts to use `COLCON_EXTENSION_BLOCKLIST`.
affects: <= 0.2.19 (before July 2022)
gotchaDesktop notifications can be intrusive and are often enabled by default. Users frequently want to disable them.fixTo 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`.
affects: All versions
gotchaOn some Linux desktop environments (e.g., Pop OS + Regolith), desktop notifications might fail with D-Bus related errors.fixEnsure 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.
affects: All versions
gotchaOn macOS, older versions had an issue with the `terminal-notifier.app` path due to a mismatch in naming conventions (underscore vs. dash).fixThis 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`.
affects: <= 0.2.19
Upgrade
Version history
0.3.1latest on PyPI · released Mar 27, 2026
Audit
Dependencies
colcon-corerequiredThis library is an extension for colcon-core.
notify2optionalProvides desktop notification API functionality on Linux systems.