Platform support

Some platforms may not support all options. For instance, some Linux desktop environments don’t support notifications with buttons. macOS and Windows don’t support manually setting the app icon or name but determine those automatically from the application which uses the Library.

The table below gives an overview over supported functionality for different platforms. Please refer to the platform documentation for more detailed information:







The application name to display




The icon shown with the notification




The notification title


The notification message


Determines persistence and appearance



One or more buttons with callbacks




An interactive reply field


A callback to invoke on click



A callback to invoke on dismissal



Play a default sound with the notification



An identifier to group notifications together


File attachment, e.g., an image





Duration until notification auto-dismissal



MacOS, Windows and almost all Linux notification servers support executing a callback when the notification is clicked. Note the requirements on a running event loop to handle callbacks in Python.


The notification urgency may influence how a notification is displayed. For instance, in Gnome, notifications of critical urgency will remain visible until closed by the user and their buttons will always be expanded.

This is currently not supported on macOS where critical notifications would require a special entitlement issued by Apple.


Our implementation for macOS 10.13 and lower supports only a single button. On iOS and macOS 10.14+, we support an unlimited number of buttons.

Linux desktop environments and notification servers may or may not support a varying number of buttons. Gnome desktops typically support up to three buttons.

Windows supports up to 5 buttons.

When an implementation or a platform supports only a limited number of buttons, any additional buttons specified in the notification request will be silently ignored.


MacOS 10.14+ and iOS support attaching a local file to the notification and may show a preview of the file. Allowed file types are:

  • An audio file up to 5 MB: AIFF, WAV, MP3, or MPEG4

  • An image file up to 10 MB: JPEG, GIF, or PNG

  • A video file up to 50 MB: MPEG, MPEG2, MPEG4, or AVI

On macOS, only previews of image attachments will be shown. iOS will show previews of all of the above attachment types and allows long-pressing the notification to show the full attachment. The notification will still be shown if the attachment cannot be loaded.

Windows supports images only. The image URI must be a web url or point to a resource bundled with the app.

Linux notification servers may support attaching a secondary image to the notification, shown in addition to the app icon. Where this is not supported, the app icon will be replaced by a thumbnail of the image. This is currently the case for Gnome.