notify2 API documentation

notify2 is - or was - a package to display desktop notifications on Linux. Those are the little bubbles which tell a user about e.g. new emails.

notify2 is deprecated. Here are some alternatives:

  • desktop_notify is a newer module doing essentially the same thing.
  • If you’re writing a GTK application, you may want to use GNotification (intro, Python API).
  • For simple cases, you can run notify-send as a subprocess. The py-notifier package provides a simple Python API around this, and can also display notifications on Windows.

notify2 is a replacement for pynotify which can be used from different GUI toolkits and from programs without a GUI. The API is largely the same as that of pynotify, but some less important parts are left out.

Notifications are sent to a notification daemon over D-Bus, according to the Desktop notifications spec, and the server is responsible for displaying them to the user. So your application has limited control over when and how a notification appears.

notify2.init(app_name, mainloop=None)[source]

Initialise the D-Bus connection. Must be called before you send any notifications, or retrieve server info or capabilities.

To get callbacks from notifications, DBus must be integrated with a mainloop. There are three ways to achieve this:

  • Set a default mainloop (dbus.set_default_main_loop) before calling init()
  • Pass the mainloop parameter as a string ‘glib’ or ‘qt’ to integrate with those mainloops. (N.B. passing ‘qt’ currently makes that the default dbus mainloop, because that’s the only way it seems to work.)
  • Pass the mainloop parameter a DBus compatible mainloop instance, such as dbus.mainloop.glib.DBusGMainLoop().

If you only want to display notifications, without receiving information back from them, you can safely omit mainloop.


Get a list of server capabilities.

These are short strings, listed in the spec. Vendors may also list extra capabilities with an ‘x-‘ prefix, e.g. ‘x-canonical-append’.


Get basic information about the server.

Creating and showing notifications

class notify2.Notification(summary, message='', icon='')[source]

A notification object.

summary : str
The title text
message : str
The body text, if the server has the ‘body’ capability.
icon : str
Path to an icon image, or the name of a stock icon. Stock icons available in Ubuntu are listed here. You can also set an icon from data in your application - see set_icon_from_pixbuf().

Ask the server to show the notification.

Call this after you have finished setting any parameters of the notification that you want.

update(summary, message='', icon=None)[source]

Replace the summary and body of the notification, and optionally its icon. You should call show() again after this to display the updated notification.


Ask the server to close this notification.

Extra parameters

class notify2.Notification[source]

Set the urgency level to one of URGENCY_LOW, URGENCY_NORMAL or URGENCY_CRITICAL.


Set the display duration in milliseconds, or one of the special values EXPIRES_DEFAULT or EXPIRES_NEVER. This is a request, which the server might ignore.

Only exists for compatibility with pynotify; you can simply set:

n.timeout = 5000

Set the ‘category’ hint for this notification.

See categories in the spec.

set_location(x, y)[source]

Set the notification location as (x, y), if the server supports it.


Set a custom icon from a GdkPixbuf.

set_hint(key, value)[source]

n.set_hint(key, value) <–> n.hints[key] = value

See hints in the spec.

Only exists for compatibility with pynotify.

set_hint_byte(key, value)[source]

Set a hint with a dbus byte value. The input value can be an integer or a bytes string of length 1.


To receive callbacks, you must have set a D-Bus event loop when you called init().

class notify2.Notification[source]
connect(event, callback)[source]

Set the callback for the notification closing; the only valid value for event is ‘closed’ (the parameter is kept for compatibility with pynotify).

The callback will be called with the Notification instance.

add_action(action, label, callback, user_data=None)[source]

Add an action to the notification.

Check for the ‘actions’ server capability before using this.

action : str
A brief key.
label : str
The text displayed on the action button
callback : callable
A function taking at 2-3 parameters: the Notification object, the action key and (if specified) the user_data.
user_data :
An extra argument to pass to the callback.



Urgency levels to pass to Notification.set_urgency().


Special expiration times to pass to Notification.set_timeout().

Indices and tables