Platform support

Some platforms may not support all options. For instance, some Linux desktop environments may not support notifications with buttons. macOS and Windows do not support manually setting the app icon or name. Instead, both are always determined by the application which uses the Library. This can be Python itself, when used interactively, or a frozen app bundle when packaged with PyInstaller or similar solutions.

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

Note

Windows support is still experimental and may have some rough edges.

Option

Description

Linux

macOS/iOS

Windows

app_name

The application name to display

1

1

app_icon

The icon shown with the notification

1

1

title

The notification title

message

The notification message

urgency

Determines persistence and appearance

2

buttons

One or more buttons with callbacks

3

4

reply_field

An interactive reply field

on_clicked

A callback to invoke on click

3

on_dismissed

A callback to invoke on dismissal

3

sound

Play a default sound with the notification

3

thread

An identifier to group notifications together

attachment

File attachment, e.g., an image

5

5

5

1(1,2,3,4)

App name and icon on macOS and Windows are automatically determined by the calling application.

2

Only on macOS 12 and later.

3(1,2,3,4)

May be ignored by some notification servers, depending on the desktop environment.

4

Only a single button is supported by our implementation for macOS 10.13 and lower.

5(1,2,3)

Limitations on file types exist for each platform.

Callbacks

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.

Urgency

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.

Buttons

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.

Attachments

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.