Desktop notifications

Desktop notifications are small, passive popup dialogs that notify the user of particular events in an asynchronous manner.

Libnotify

Libnotify is an implementation of the Desktop Notifications Specification which provides support for GTK and Qt applications and is desktop independent: it is already used by many open source applications like Evolution and Pidgin. Libnotify can be installed with the libnotify package.

In order to use libnotify, you have to install a notification server.

Notification servers

Built-in

Cinnamon, Deepin, Enlightenment, GNOME, GNOME Flashback and KDE Plasma use their own implementations to display notifications, and it cannot be replaced. Their notification servers are started automatically on login to receive notifications from applications via DBus.

Standalone

In other desktop environments, the notification server needs to be launched using an autostarting option.

Alternatively, making the notification server as a D-Bus service, the notification server can be launched automatically on the first call to it. For example, after installing the notification-daemon package, add the following configuration to D-Bus services directory (/usr/share/dbus-1/services or $XDG_DATA_HOME/dbus-1/services):

org.freedesktop.Notifications.service

[D-BUS Service]
Name=org.freedesktop.Notifications
Exec=/usr/lib/notification-daemon-1.0/notification-daemon

Whenever an application sends a notification by sending a signal to org.freedesktop.Notifications, D-Bus activates /usr/lib/notification-daemon-1.0/notification-daemon if it has not already been activated.

You can also choose one of the following implementations:

• mako — A lightweight notification daemon for Wayland; it currently works on Sway.

https://github.com/emersion/mako || mako

• Notification Daemon — The original notification server.

https://gitlab.gnome.org/Archive/notification-daemon || notification-daemon

You can run it manually using /usr/lib/notification-daemon-1.0/notification-daemon.

You can run it manually using /usr/lib/xfce4/notifyd/xfce4-notifyd.

Usage in programming

You can write your own libnotify display messages easily in many programming languages through GObject-Introspection or bindings, or you can simply use bash.

The following examples display a simple "Hello world" notification.

Bash

• Dependency: libnotify

• Dependency: glib2

Boo

• Dependency: ()
• Makedependency:
• Build with:
• Run with: mono hello_world.exe (or )

C

• Dependency: glib2
• Build with:

• Dependency: libnotify
• Build with: gcc -o hello_world `pkg-config --cflags --libs libnotify` hello_world.c

• Dependency:
• Build with:

C++

• Dependency: glibmm
• Build with:

• Dependency:
• Build with:

C#

• Dependency:
• Build with: mcs -pkg:notify-sharp-3.0 hello_world.cs
• Run with: mono hello_world.exe

Crystal

• Dependency: woodruffw/notify.cr (from shards)
• Build with: shards build

F#

• Dependency:
• Makedependency:
• Build with:
• Run with: mono hello_world.exe

hello_world.fs

open Notifications
let Hello = new Notification()
Hello.Summary  <- "Hello world!"
Hello.Body     <- "This is an example notification."
Hello.IconName <- "dialog-information"
Hello.Show()

Genie

• Dependency: glib2
• Makedependency:
• Build with:

• Dependency: libnotify
• Makedependency:
• Build with:

Go

• Dependency: libnotify
• Makedependency: go-notify-git^AUR
• Build with:
• (Or run with: )

Groovy

• Dependencies: , java-gnome^AUR
• Build with:
• Run with: or

Haskell

• Makedependency:
• Build with:

IronPython

• Dependencies: , ironpython^AUR
• Run with:

Java

• Dependency: java-gnome^AUR
• Makedependency: java-environment
• Build with:
• Run with: java -cp /usr/share/java/gtk.jar:HelloWorld.jar HelloWorld

JavaScript

• Dependency:

• Dependencies: libnotify,

• Dependencies: , node-dbus-notifier

JRuby

• Dependencies: java-gnome^AUR, jruby
• Build with:
• Run with: or

hello_world.rb

require '/usr/share/java/gtk.jar'
import Java::OrgGnomeGtk::Gtk
import Java::OrgGnomeNotify::Notify
import Java::OrgGnomeNotify::Notification

Gtk.init(nil)
Notify.init("Hello world")
Hello = Notification.new("Hello world!", "This is an example notification.", "dialog-information")
Hello.show

Jython

• Dependencies: java-gnome^AUR,
• Run with:

Lua

• Dependency:

• Dependencies: libnotify,

Nemerle

• Dependency:
• Makedependency: nemerle^AUR
• Build with:
• Run with: mono hello_world.exe

Pascal

• Dependency: libnotify
• Makedependency: fpc, libnotify binding
• Build with:

Using libnotify

• Dependencies: libnotify,

Using direct D-Bus calls

• Dependencies: perl-net-dbus

Python

• Dependency:

• Dependencies: libnotify,

• Dependency: dbus-python

For the arguments in the method , please refer to the section of org.freedesktop.Notifications.Notify at Desktop Notifications Specification.

Ruby

• Dependencies: libnotify,

Rust

Using notify-rust.

• Makedependency: rust
• Build with:
• Run with: target/debug/hello_world or cargo run

Scala

• Dependency: java-gnome^AUR (and )
• Makedependency:
• Build with:
• Run with: java -cp /usr/share/java/gtk.jar:HelloWorld.jar HelloWorld (or )

HelloWorld.scala

import org.gnome.gtk._
import org.gnome.notify._

object HelloWorld {
  def main(args: Array[String]) {
    Gtk.init(args)
    Notify.init("Hello world")
    var Hello = new Notification("Hello world!", "This is an example notification.", "dialog-information")
    Hello.show()
  }
}

Vala

• Dependency: glib2
• Makedependency:
• Build with: valac --pkg gio-2.0 hello_world.vala

• Dependency: libnotify
• Makedependency:
• Build with:

Visual Basic .NET

• Dependency:
• Makedependency:
• Build with: vbnc -r:/usr/lib/mono/notify-sharp-3.0/notify-sharp.dll hello_world.vb
• Run with: mono hello_world.exe

Tips and tricks

Replace previous notification

Notifications can be replaced if their ID is known; if a new notification request specifies the same ID, it will always replace the old notification. (The libnotify bindings shown above handle this automatically.) Unfortunately notify-send does not report this ID, so alternative tools are required to do this on CLI. One capable CLI-tool is the notify-send.py python script, which provides notify-send syntax with additional ID-reporting and replacing capabilities.

However, with some notification servers (such as Notify-OSD), you can use the hint with notify-send to achieve the same result.

For example, to get a notification displaying time:

Include Buttons or listen for close/on-click of the notification

With the notify-send.py script, actions can be used to display buttons or to listen for the default-action of the notification (usually, when the user clicks on it) and the close-action. When the action-icons hint is set to true and the notification daemon supports this, the buttons will display icons instead of text. The script prints the action identifier or "close" to the command line when the corresponding event has occured. To listen for the default action (on-click), one has to use the action-identfier "default".

Example with icons on buttons:

Multiple notification servers with D-Bus services

As described in the section Standalone, users can create a D-Bus service so that a notification server can be launched automatically. Some implementations already include the D-Bus service files. However, this causes a problem when multiple notification servers are installed and when some of them come with the service files. For example, installing both and without explicitly specifying the desired server, D-Bus then chooses one for the users, and the decision is out of users' control. To avoid the situation, you can override the service used by creating the symbolic link $XDG_DATA_DIR/dbus-1/services/org.freedesktop.Notifications.service pointing to the service you want to use, and then restart the session.

Troubleshooting

Applications hanging for exactly one minute

If applications hang when attempting to show notifications, it might be because of a notification service falsely advertising its availability through the D-Bus service.

For instance, suppose a user recently installed a KDE component that requires , but the user is still running XFCE. In this case, the KDE notifier will be prioritized, but the user is not running it. The application will hang while waiting for the service, and only after a timeout will it fall back to xfce4-notifyd.

The most noticeable hanging might come from the volume indicator scroll adjustment.

If you are in this situation, you should have two notification handlers:

Of those two, one fails regularly after a 1-minute timeout, as seen in the journal:

Choosing the service you want to use as described in #Multiple notification servers with D-Bus services will fix the problem.

See also

• Libnotify Reference Manual
• C example (archived version)
• Python notification examples
• Python notify example (french article)