DESKTOP-NOTIFIER(1)

NAME
desktop-notifier - desktop-notifier 6.1.1

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:

•   macOS / iOS: UNUserNotificationCenter <https://developer.apple.com/documentation/usernotifications/unusernotificationcenter>

•   Linux: org.freedesktop.Notifications <https://specifications.freedesktop.org/notification-spec/notification-spec-latest.html>

•   Windows: Toast Notifications <https://docs.microsoft.com/windows/apps/design/shell/tiles-and-notifications/adaptive-interactive-toasts>
    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] | ✓ [3] | ✓
    buttons | One or more buttons with callbacks | ✓ [4] | ✓ | ✓ [4]
    reply_field | An interactive reply field | -- | ✓ | ✓
    on_clicked | A callback to invoke on click | ✓ | ✓ | ✓
    on_dismissed | A callback to invoke on dismissal | ✓ | ✓ | ✓
    sound | Play a sound with the notification | ✓ [2] | ✓ [5] | ✓
    thread | An identifier to group notifications together | -- | ✓ | ✓
    attachment | File attachment, e.g., an image | ✓ [2] [6] | ✓ [6] | ✓ [6]
    timeout | Duration in seconds until notification auto-dismissal | ✓ | -- | --

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

[2] May be ignored by some Linux notification servers.

[3] Only on macOS 12 and later.

[4] Number of buttons may be limited. See section below.

[5] macOS only supports named sounds, e.g., from /System/Library/Sounds.

[6] Limitations on file types exist for each platform. See section below.

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.

On macOS, critical notifications require a special app entitlement issued by Apple.

BUTTONS

macOS supports 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.

    Using the asynchronous API is highly recommended to prevent multiple milliseconds of blocking IO from DBus or Cocoa APIs. In addition, execution of callbacks requires a running event loop. On Linux, an asyncio event loop will be sufficient but macOS requires a running CFRunLoop <https://developer.apple.com/documentation/corefoundation/cfrunloop-rht>.

    You can use rubicon-objc <https://github.com/beeware/rubicon-objc> to integrate a Core Foundation CFRunLoop with asyncio:

        import asyncio
        from rubicon.objc.eventloop import EventLoopPolicy
        # Install the event loop policy
        asyncio.set_event_loop_policy(EventLoopPolicy())

    Desktop-notifier itself uses Rubicon Objective-C to interface with Cocoa APIs so you will not be adding a new dependency. A full example integrating with the CFRunLoop is given in examples folder. Please refer to the Rubicon Objective-C docs <https://rubicon-objc.readthedocs.io/en/latest/how-to/async.html> for more information.

    Likewise, you can integrate the asyncio event loop with a Gtk main loop on Gnome using gbulb <https://pypi.org/project/gbulb/>. This is not required for full functionality but may be convenient when developing a Gtk app.

    Thank you for your interest in contributing!

    If you would like to contribute more than a simple bug fix, please open an issue first to discuss potential changes before implementing them.

CODE

To start, install maestral with the dev extra to get all dependencies required for development:

    pip3 install 'desktop-notifier[dev]'

This will install packages to check and enforce the code style, use pre-commit hooks and bump the current version.

Code is formatted with black <https://github.com/psf/black>. Coding style is checked with flake8 <http://flake8.pycqa.org>. Type hints, PEP484 <https://www.python.org/dev/peps/pep-0484/>, are checked with mypy <http://mypy-lang.org/>.

TESTS

Tests are currently very limited because it is challenging to verify that a notification was indeed displayed as intended. Instead, we focus on:

•   Testing API contracts around showing and clearing notifications

•   Smoke tests to ensure no exceptions or segfaults during usage on supported platforms

    This page contains auto-generated API reference documentation [1].

DESKTOP_NOTIFIER

Desktop notifications for Windows, Linux, macOS, iOS and iPadOS.

  Submodules

  desktop_notifier.common

This module defines base classes for desktop notifications.

  Attributes
DEFAULT_ICON | Python icon
DEFAULT_SOUND | Default system notification sound

  Exceptions
AuthorisationError | Raised when we are not authorised to send notifications

  Classes
FileResource | A file resource represented by a URI or path
Resource | A resource represented by a resource name, URI or path
Icon | An icon represented by an icon name, URI or path
Attachment | An attachment represented by a URI or path
Sound | A sound represented by a sound name, URI or path
Urgency | Enumeration of notification levels
Button | A button for interactive notifications
ReplyField | A text field for interactive notifications
Notification | A desktop notification
Capability | Notification capabilities that can be supported by a platform

  Module Contents

class desktop_notifier.common.FileResource
    A file resource represented by a URI or path

    Only one of path or uri can be set.

path: pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> | None <https://docs.python.org/3/library/constants.html#None> = None
    Path to a local file

uri: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None
    URI reference to a file

as_uri()
    Returns the represented resource as a URI string

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

as_path()
    Returns the represented resource as a Path

    Note that any information about the URI scheme is lost on conversion.

Return type
    pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>

class desktop_notifier.common.Resource
    Bases: FileResource

    A resource represented by a resource name, URI or path

    Only one of path, uri or name can be set.

name: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None
    Name of the system resource

is_named()
    Returns whether the instance was initialized with name

Return type
    bool <https://docs.python.org/3/library/functions.html#bool>

is_file()
    Returns whether the instance was initialized with path or uri

Return type
    bool <https://docs.python.org/3/library/functions.html#bool>

class desktop_notifier.common.Icon
    Bases: Resource

    An icon represented by an icon name, URI or path

class desktop_notifier.common.Attachment
    Bases: FileResource

    An attachment represented by a URI or path

class desktop_notifier.common.Sound
    Bases: Resource

    A sound represented by a sound name, URI or path

desktop_notifier.common.DEFAULT_ICON: Icon <#desktop_notifier.common.Icon>
    Python icon

desktop_notifier.common.DEFAULT_SOUND: Sound <#desktop_notifier.common.Sound>
    Default system notification sound

exception desktop_notifier.common.AuthorisationError
    Bases: Exception <https://docs.python.org/3/library/exceptions.html#Exception>

    Raised when we are not authorised to send notifications

class desktop_notifier.common.Urgency
    Bases: enum.Enum <https://docs.python.org/3/library/enum.html#enum.Enum>

    Enumeration of notification levels

    The interpretation and visuals depend on the platform.

Critical = 'critical'
    For critical errors.

Normal = 'normal'
    Default platform notification level.

Low = 'low'
    Low priority notification.

class desktop_notifier.common.Button
    A button for interactive notifications

title: str <https://docs.python.org/3/library/stdtypes.html#str>
    The localized button title

on_pressed: Callable[[], Any] | None <https://docs.python.org/3/library/constants.html#None> = None
    Method to call when the button is pressed

identifier: str <https://docs.python.org/3/library/stdtypes.html#str> = ''
    A unique identifier to use in callbacks to specify with button was clicked

class desktop_notifier.common.ReplyField
    A text field for interactive notifications

title: str <https://docs.python.org/3/library/stdtypes.html#str> = 'Reply'
    A title for the field itself. On macOS, this will be the title of a button to show the field.

button_title: str <https://docs.python.org/3/library/stdtypes.html#str> = 'Send'
    The title of the button to send the reply

on_replied: Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None <https://docs.python.org/3/library/constants.html#None> = None
    Method to call when the 'reply' button is pressed

class desktop_notifier.common.Notification
    A desktop notification

    Some properties of a notification may be ignored or interpreted differently depending on the platform.

    Callbacks for interactions will be executed on the Python process that scheduled the notification and only as long as the DesktopNotifier instance that scheduled the notification still exists.

    Install handlers on the DesktopNotifier instance itself to respond to interactions with notification from your app while it was not running.

title: str <https://docs.python.org/3/library/stdtypes.html#str>
    Notification title

message: str <https://docs.python.org/3/library/stdtypes.html#str>
    Notification message

urgency: Urgency <#desktop_notifier.common.Urgency>
    Notification urgency. Can determine stickiness, notification appearance and break through silencing.

icon: Icon <#desktop_notifier.common.Icon> | None <https://docs.python.org/3/library/constants.html#None> = None
    Icon to use for the notification

buttons: tuple <https://docs.python.org/3/library/stdtypes.html#tuple>[Button <#desktop_notifier.common.Button>, Ellipsis] = ()
    Buttons shown on an interactive notification

reply_field: ReplyField <#desktop_notifier.common.ReplyField> | None <https://docs.python.org/3/library/constants.html#None> = None
    Text field shown on an interactive notification. This can be used for example for messaging apps to reply directly from the notification.

on_dispatched: Callable[[], Any] | None <https://docs.python.org/3/library/constants.html#None> = None
    Method to call when the notification was sent to the notifications server for display

on_clicked: Callable[[], Any] | None <https://docs.python.org/3/library/constants.html#None> = None
    Method to call when the notification is clicked

on_dismissed: Callable[[], Any] | None <https://docs.python.org/3/library/constants.html#None> = None
    Method to call when the notification is dismissed

attachment: Attachment <#desktop_notifier.common.Attachment> | None <https://docs.python.org/3/library/constants.html#None> = None
    A file attached to the notification which may be displayed as a preview

sound: Sound <#desktop_notifier.common.Sound> | None <https://docs.python.org/3/library/constants.html#None> = None
    A sound to play on notification

thread: str <https://docs.python.org/3/library/stdtypes.html#str> | None <https://docs.python.org/3/library/constants.html#None> = None
    An identifier to group related notifications together, e.g., from a chat space

timeout: int <https://docs.python.org/3/library/functions.html#int> = -1
    Duration in seconds for which the notification is shown

identifier: str <https://docs.python.org/3/library/stdtypes.html#str> = ''
    A unique identifier for this notification. Generated automatically if not passed by the client.

class desktop_notifier.common.Capability
    Bases: enum.Enum <https://docs.python.org/3/library/enum.html#enum.Enum>

    Notification capabilities that can be supported by a platform

APP_NAME
    Supports setting a custom app name

TITLE
    Supports setting a notification title

MESSAGE
    Supports setting a notification message

URGENCY
    Supports different urgency levels

ICON
    Supports custom notification icons

ICON_FILE
    Supports setting a custom icon from a user-provided file

ICON_NAME
    Supports setting a named system icon as notification icon

BUTTONS
    Supports at least two notification buttons

REPLY_FIELD
    Supports reply fields

ATTACHMENT
    Supports notification attachments. Allowed file types vary by platform.

ON_DISPATCHED
    Supports on-dispatched callbacks

ON_CLICKED
    Supports on-clicked callbacks

ON_DISMISSED
    Supports on-dismissed callbacks

SOUND
    Supports custom notification sounds

SOUND_FILE
    Supports setting a custom sound from a user-provided file

SOUND_NAME
    Supports setting a named system sound as notification sound

THREAD
    Supports grouping notifications by topic thread

TIMEOUT
    Supports notification timeouts

  desktop_notifier.main

Asynchronous desktop notification API

  Classes
DesktopNotifier | Cross-platform desktop notification emitter

  Module Contents

class desktop_notifier.main.DesktopNotifier(app_name='Python', app_icon=DEFAULT_ICON, notification_limit=None)
    Cross-platform desktop notification emitter

    Uses different backends depending on the platform version and available services. All implementations will dispatch notifications without an event loop but will require a running event loop to execute callbacks when the end user interacts with a notification. On Linux, an asyncio event loop is required. On macOS, a CFRunLoop in the main thread is required. Packages such as rubicon.objc can be used to integrate asyncio with a CFRunLoop.

    Callbacks to handle user interactions with a notification can be specified either at the class level, where they take the notification identifier as input, or directly on the notification itself. The latter will take precedence if set.

    Note that handlers that are directly set on the notification are tied to Python notification instance and therefore the app's lifecycle. Handlers that are set on the class level may run also for interactions with a notification while the app was not running, if DesktopNotifier is instantiated at app startup.

Parameters

•   app_name (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Name to identify the application in the notification center. On Linux, this should correspond to the application name in a desktop entry. On macOS, this argument is ignored and the app is identified by the bundle ID of the sending program (e.g., Python).

•   app_icon (desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None) -- Default icon to use for notifications. This should be a desktop_notifier.base.Icon instance referencing either a file or a named system icon. str <https://docs.python.org/3/library/stdtypes.html#str> or pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path> are also accepted but deprecated.

•   notification_limit (int <https://docs.python.org/3/library/functions.html#int> | None)

property app_name: str <https://docs.python.org/3/library/stdtypes.html#str>
    The application name

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

property app_icon: desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None <https://docs.python.org/3/library/constants.html#None>
    The application icon

Return type
    desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None

async request_authorisation()
    Requests authorisation to send user notifications. This will be automatically called for you when sending a notification for the first time. It also can be called manually to request authorisation in advance.

    On some platforms such as macOS and iOS, a prompt will be shown to the user when this method is called for the first time. This method does nothing on platforms where user authorisation is not required.

Returns
    Whether authorisation has been granted.

Return type
    bool <https://docs.python.org/3/library/functions.html#bool>

async has_authorisation()
    Returns whether we have authorisation to send notifications.

Return type
    bool <https://docs.python.org/3/library/functions.html#bool>

async send_notification(notification)
    Sends a desktop notification.

    This method does not raise an exception when scheduling the notification fails but logs warnings instead.

    Note that even a successfully scheduled notification may not be displayed to the user, depending on their notification center settings (for instance if "do not disturb" is enabled on macOS).

Parameters
    notification (desktop_notifier.common.Notification <#desktop_notifier.common.Notification>) -- The notification to send.

Returns
    An identifier for the scheduled notification.

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

async send(title, message, urgency=Urgency.Normal, icon=None, buttons=(), reply_field=None, on_dispatched=None, on_clicked=None, on_dismissed=None, attachment=None, sound=None, thread=None, timeout=-1)
    Sends a desktop notification

    This is a convenience function which creates a desktop_notifier.base.Notification with the provided arguments and then calls send_notification().

Returns
    An identifier for the scheduled notification.

Parameters

•   title (str <https://docs.python.org/3/library/stdtypes.html#str>)

•   message (str <https://docs.python.org/3/library/stdtypes.html#str>)

•   urgency (desktop_notifier.common.Urgency <#desktop_notifier.common.Urgency>)

•   icon (desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None)

•   buttons (Sequence[desktop_notifier.common.Button <#desktop_notifier.common.Button>])

•   reply_field (desktop_notifier.common.ReplyField <#desktop_notifier.common.ReplyField> | None)

•   on_dispatched (Callable[[], Any] | None)

•   on_clicked (Callable[[], Any] | None)

•   on_dismissed (Callable[[], Any] | None)

•   attachment (desktop_notifier.common.Attachment <#desktop_notifier.common.Attachment> | None)

•   sound (desktop_notifier.common.Sound <#desktop_notifier.common.Sound> | None)

•   thread (str <https://docs.python.org/3/library/stdtypes.html#str> | None)

•   timeout (int <https://docs.python.org/3/library/functions.html#int>)

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

async get_current_notifications()
    Returns identifiers of all currently displayed notifications for this app.

Return type
    list <https://docs.python.org/3/library/stdtypes.html#list>[str <https://docs.python.org/3/library/stdtypes.html#str>]

async clear(identifier)
    Removes the given notification from the notification center.

Parameters
    identifier (str <https://docs.python.org/3/library/stdtypes.html#str>) -- Notification identifier.

Return type
    None

async clear_all()
    Removes all currently displayed notifications for this app from the notification center.

Return type
    None

async get_capabilities()
    Returns which functionality is supported by the implementation.

Return type
    frozenset <https://docs.python.org/3/library/stdtypes.html#frozenset>[desktop_notifier.common.Capability <#desktop_notifier.common.Capability>]

property on_dispatched: Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None <https://docs.python.org/3/library/constants.html#None>
    A method to call when a notification is sent to the notifications server

    The method must take the notification identifier as a single argument.

    If the notification itself already specifies an on_dispatched handler, it will be used instead of the class-level handler.

Return type
    Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None

property on_clicked: Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None <https://docs.python.org/3/library/constants.html#None>
    A method to call when a notification is clicked

    The method must take the notification identifier as a single argument.

    If the notification itself already specifies an on_clicked handler, it will be used instead of the class-level handler.

Return type
    Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None

property on_dismissed: Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None <https://docs.python.org/3/library/constants.html#None>
    A method to call when a notification is dismissed

    The method must take the notification identifier as a single argument.

    If the notification itself already specifies an on_dismissed handler, it will be used instead of the class-level handler.

Return type
    Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None

property on_button_pressed: Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>, str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None <https://docs.python.org/3/library/constants.html#None>
    A method to call when one of the notification's buttons is clicked

    The method must take the notification identifier and the button identifier as arguments.

    If the notification button itself already specifies an on_pressed handler, it will be used instead of the class-level handler.

Return type
    Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>, str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None

property on_replied: Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>, str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None <https://docs.python.org/3/library/constants.html#None>
    A method to call when a user responds through the reply field of a notification

    The method must take the notification identifier and input text as arguments.

    If the notification's reply field itself already specifies an on_replied handler, it will be used instead of the class-level handler.

Return type
    Callable[[str <https://docs.python.org/3/library/stdtypes.html#str>, str <https://docs.python.org/3/library/stdtypes.html#str>], Any] | None

  desktop_notifier.sync

Synchronous desktop notification API

  Classes
DesktopNotifierSync | A synchronous counterpart to desktop_notifier.main.DesktopNotifier <#desktop_notifier.main.DesktopNotifier>

  Module Contents

class desktop_notifier.sync.DesktopNotifierSync(app_name='Python', app_icon=DEFAULT_ICON, notification_limit=None)
    A synchronous counterpart to desktop_notifier.main.DesktopNotifier <#desktop_notifier.main.DesktopNotifier>

    Warning: Callbacks on interaction with the notification will not work on macOS or Linux without a running event loop.

Parameters

•   app_name (str <https://docs.python.org/3/library/stdtypes.html#str>)

•   app_icon (desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None)

•   notification_limit (int <https://docs.python.org/3/library/functions.html#int> | None)

property app_name: str <https://docs.python.org/3/library/stdtypes.html#str>
    The application name

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

property app_icon: desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None <https://docs.python.org/3/library/constants.html#None>
    The application icon

Return type
    desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None

request_authorisation()
    See desktop_notifier.main.DesktopNotifier.request_authorisation() <#desktop_notifier.main.DesktopNotifier.request_authorisation>

Return type
    bool <https://docs.python.org/3/library/functions.html#bool>

has_authorisation()
    See desktop_notifier.main.DesktopNotifier.has_authorisation() <#desktop_notifier.main.DesktopNotifier.has_authorisation>

Return type
    bool <https://docs.python.org/3/library/functions.html#bool>

send_notification(notification)
    See desktop_notifier.main.DesktopNotifier.send_notification() <#desktop_notifier.main.DesktopNotifier.send_notification>

Parameters
    notification (desktop_notifier.common.Notification <#desktop_notifier.common.Notification>)

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

send(title, message, urgency=Urgency.Normal, icon=None, buttons=(), reply_field=None, on_dispatched=None, on_clicked=None, on_dismissed=None, attachment=None, sound=None, thread=None, timeout=-1)
    See desktop_notifier.main.DesktopNotifier.send() <#desktop_notifier.main.DesktopNotifier.send>

Parameters

•   title (str <https://docs.python.org/3/library/stdtypes.html#str>)

•   message (str <https://docs.python.org/3/library/stdtypes.html#str>)

•   urgency (desktop_notifier.common.Urgency <#desktop_notifier.common.Urgency>)

•   icon (desktop_notifier.common.Icon <#desktop_notifier.common.Icon> | None)

•   buttons (Sequence[desktop_notifier.common.Button <#desktop_notifier.common.Button>])

•   reply_field (desktop_notifier.common.ReplyField <#desktop_notifier.common.ReplyField> | None)

•   on_dispatched (Callable[[], Any] | None)

•   on_clicked (Callable[[], Any] | None)

•   on_dismissed (Callable[[], Any] | None)

•   attachment (desktop_notifier.common.Attachment <#desktop_notifier.common.Attachment> | None)

•   sound (desktop_notifier.common.Sound <#desktop_notifier.common.Sound> | None)

•   thread (str <https://docs.python.org/3/library/stdtypes.html#str> | None)

•   timeout (int <https://docs.python.org/3/library/functions.html#int>)

Return type
    str <https://docs.python.org/3/library/stdtypes.html#str>

get_current_notifications()
    See desktop_notifier.main.DesktopNotifier.get_current_notifications() <#desktop_notifier.main.DesktopNotifier.get_current_notifications>

Return type
    list <https://docs.python.org/3/library/stdtypes.html#list>[str <https://docs.python.org/3/library/stdtypes.html#str>]

clear(identifier)
    See desktop_notifier.main.DesktopNotifier.clear() <#desktop_notifier.main.DesktopNotifier.clear>

Parameters
    identifier (str <https://docs.python.org/3/library/stdtypes.html#str>)

Return type
    None

clear_all()
    See desktop_notifier.main.DesktopNotifier.clear_all() <#desktop_notifier.main.DesktopNotifier.clear_all>

Return type
    None

get_capabilities()
    See desktop_notifier.main.DesktopNotifier.get_capabilities() <#desktop_notifier.main.DesktopNotifier.get_capabilities>

Return type
    frozenset <https://docs.python.org/3/library/stdtypes.html#frozenset>[desktop_notifier.common.Capability <#desktop_notifier.common.Capability>]

[1] Created with sphinx-autoapi <https://github.com/readthedocs/sphinx-autoapi> [image: PyPi Release] [image]
     <https://pypi.org/project/desktop-notifier/>[image: Pyversions] [image]
     <https://pypi.org/pypi/desktop-notifier/>[image: Documentation Status] [image]
     <https://desktop-notifier.readthedocs.io/en/latest/?badge=latest>

    desktop-notifier is a Python library for cross-platform desktop notifications. Currently supported platforms are:

•   Linux via the dbus service org.freedesktop.Notifications

•   macOS and iOS via the Notification Center framework

•   Windows via the WinRT / Python bridge

FEATURES

Where supported by the native platform APIs, desktop-notifier allows for:

•   Clickable notifications with callbacks on user interaction

•   Multiple action buttons

•   A single reply field (e.g., for chat notifications)

•   Notification sounds

•   Notification threads (grouping notifications by topic)

•   Limiting the maximum number of notifications shown in the notification center

    An example of how some of this looks like on macOS: [image: gif] [image]
     <https://github.com/samschott/desktop-notifier/blob/main/screenshots/macOS.gif?raw=true>

    An exhaustive list of features and their platform support is provided in the documentation <https://desktop-notifier.readthedocs.io/en/latest/background/platform_support.html>. In addition, you can query supported features at runtime with DesktopNotifier.get_capabilities().

    Any options or configurations which are not supported by the platform will be silently ignored.

INSTALLATION

From PyPI:

    pip3 install -U desktop-notifier

USAGE

The main API consists of asynchronous methods which need to be awaited. Basic usage only requires the user to specify a notification title and message. For example:

    import asyncio
    from desktop_notifier import DesktopNotifier
    notifier = DesktopNotifier()
    async def main():
        await notifier.send(title="Hello world!", message="Sent from Python")
    asyncio.run(main())

By default, "Python" will be used as the app name for all notifications, but you can manually specify an app name and icon in the DesktopNotifier constructor. Advanced usage also allows setting different notification options such as urgency, buttons, callbacks, etc. For example, for the gif displayed above:

    import asyncio
    import signal
    from desktop_notifier import DesktopNotifier, Urgency, Button, ReplyField, DEFAULT_SOUND
    async def main() -> None:
        notifier = DesktopNotifier(app_name="Sample App")
        await notifier.send(
            title="Julius Caesar",
            message="Et tu, Brute?",
            urgency=Urgency.Critical,
            buttons=[
                Button(
                    title="Mark as read",
                    on_pressed=lambda: print("Marked as read"),
                )
            ],
            reply_field=ReplyField(
                on_replied=lambda text: print("Brutus replied:", text),
            ),
            on_dispatched=lambda: print("Notification showing"),
            on_clicked=lambda: print("Notification clicked"),
            on_dismissed=lambda: print("Notification dismissed"),
            sound=DEFAULT_SOUND,
        )
        # Run the event loop forever to respond to user interactions with the notification.
        stop_event = asyncio.Event()
        loop = asyncio.get_running_loop()
        loop.add_signal_handler(signal.SIGINT, stop_event.set)
        loop.add_signal_handler(signal.SIGTERM, stop_event.set)
        await stop_event.wait()
    asyncio.run(main())

EVENT LOOP INTEGRATION

Using the asynchronous API is highly recommended to prevent multiple milliseconds of blocking IO from DBus or Cocoa APIs. In addition, execution of callbacks requires a running event loop. On Linux, an asyncio event loop will be sufficient but macOS requires a running CFRunLoop <https://developer.apple.com/documentation/corefoundation/cfrunloop-rht>.

You can use rubicon-objc <https://github.com/beeware/rubicon-objc> to integrate a Core Foundation CFRunLoop with asyncio:

    import asyncio
    from rubicon.objc.eventloop import EventLoopPolicy
    # Install the event loop policy
    asyncio.set_event_loop_policy(EventLoopPolicy())

Desktop-notifier itself uses Rubicon Objective-C to interface with Cocoa APIs. A full example integrating with the CFRunLoop is given in <examples/eventloop.py>. Please refer to the Rubicon Objective-C docs <https://rubicon-objc.readthedocs.io/en/latest/how-to/async.html> for more information.

Likewise, you can integrate the asyncio event loop with a Gtk main loop on Gnome using gbulb <https://pypi.org/project/gbulb>. This is not required for full functionality but may be convenient when developing a Gtk app.

NOTES ON MACOS

On macOS 10.14 and higher, the implementation uses the UNUserNotificationCenter instead of the deprecated NSUserNotificationCenter. UNUserNotificationCenter only allows signed executables to send desktop notifications. This means that notifications will only work if the Python executable or bundled app has been signed. Note that the installer from python.org <https://python.org> provides a properly signed Python framework but homebrew does not (manually signing the executable installed by homebrew should work as well).

If you freeze your code with PyInstaller or a similar packaging solution, you must sign the resulting app bundle for notifications to work. An ad-hoc signature will be sufficient but signing with an Apple developer certificate is recommended for distribution and may be required on future releases of macOS.

DESIGN CHOICES

This package is opinionated in a few ways:

•   It does not try to work around platform restrictions, such as changing the app icon on macOS. Workarounds would be hacky and likely be rejected by an App Store review.

•   The main API consists of async methods and a running event loop is required to respond to user interactions with a notification. This simplifies integration with GUI apps.

•   Dependencies are pure Python packages without extension modules. This simplifies app bundling and distribution. We make an exception for Windows because interoperability with the Windows Runtime is difficult to achieve without extension modules.

•   If a certain feature is not supported by a platform, using it will not raise an exception. This allows clients to use a wide feature set where available without worrying about exception handling.

•   If a notification cannot be scheduled, this is logged as a warning and does not raise an exception. Most platforms allow the user to control if and how notifications are delivered and notification delivery therefore cannot be taken as guaranteed.

DEPENDENCIES

•   dbus-next <https://github.com/altdesktop/python-dbus-next> on Linux

•   rubicon-objc <https://github.com/beeware/rubicon-objc> on macOS

•   pywinrt <https://github.com/pywinrt/pywinrt> on Windows

Author
Sam Schott

Copyright
2026, Sam Schott