notify2 - DBus Desktop Notifications

Common errors

• dbus.exceptions.DBusException: The name org.freedesktop.Notifications was not provided by any .service files

  cause No desktop notification daemon is running on the system or it's not properly registered with DBus.
  fix Install a desktop notification daemon (e.g., `sudo apt install notification-daemon` or `dunst`) and ensure it's running and accessible to your user session.

• ImportError: No module named 'dbus'

  cause The `dbus-python` package, a core dependency for DBus communication, is not installed.
  fix Install `dbus-python` using pip: `pip install dbus-python`. On some systems, this might require system-level DBus development libraries (e.g., `libdbus-1-dev` and `libdbus-glib-1-dev` on Debian/Ubuntu).

• Notification doesn't appear on screen, with no error messages in the terminal.

  cause This is often a silent failure indicating that the notification daemon is not properly configured, not running, or the desktop environment is suppressing notifications. This can also happen if the `notify2.init()` call is missing or incorrect.
  fix 1. Ensure `notify2.init("AppName")` is called at the beginning of your script. 2. Verify your notification daemon is active and check its logs for errors. 3. Check your system's notification settings and ensure they are not globally disabled. 4. Try a simple example from the quickstart to isolate the issue.

Warnings

• gotcha notify2 relies on `dbus-python` and a running DBus session along with a compatible desktop notification daemon (e.g., `dunst`, `xfce4-notifyd`, `notification-daemon`) on a Linux desktop environment. If these prerequisites are not met, notifications will either silently fail to appear or raise `DBusException` errors.
  Fix: Ensure `dbus-python` is installed (`pip install dbus-python`) and a notification daemon is active and configured in your desktop environment. For server-side applications, this library is generally unsuitable.
• deprecated notify2 is the spiritual successor to the older `pynotify` library. While both interfaces with `libnotify`, `notify2` is generally preferred for modern Python applications and offers a more Pythonic API. If migrating from `pynotify`, expect API changes.
  Fix: Update import statements and API calls from `pynotify` to `notify2`'s syntax (e.g., `notify2.Notification` instead of `pynotify.Notification`).
• gotcha The library's last update was in 2017 (version 0.3.1). While it generally remains functional, it might encounter subtle compatibility issues with very recent Python versions (e.g., Python 3.10+) or highly specific modern DBus configurations or desktop environments. It is not actively maintained.
  Fix: Test `notify2` thoroughly in your target environment. If persistent issues arise, consider exploring alternative notification mechanisms or newer Python libraries if available and maintained.

Install

• pip install notify2 Install notify2

Imports

• notify2

  import notify2

• Notification

  n = notify2.Notification(...)

Quickstart

This quickstart initializes `notify2`, creates a basic desktop notification with a summary, body, and icon, sets a timeout, and displays it. Requires a running DBus session and a notification daemon (e.g., dunst, xfce4-notifyd) on a Linux desktop environment.

import notify2
import os

# Initialize the notification system with your app name
# This is required before sending any notifications
notify2.init(os.environ.get('NOTIFY_APP_NAME', 'MyPythonApp'))

# Create a new notification
# Arguments: summary, body (optional), icon (optional)
n = notify2.Notification(
    "Hello from notify2!", 
    "This is a test notification generated by a Python script.",
    icon='dialog-information' # Example icon name (often from GTK/freedesktop theme)
)

# Set a timeout for the notification (in milliseconds)
# -1 means 'never expire' (if supported by daemon), 0 means 'default'
n.set_timeout(5000) # 5 seconds

# Show the notification
n.show()
print("Notification sent! Check your desktop.")