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.

gollark: Destroy mankind.

gollark: It's populace.

gollark: They're owner.

gollark: Sort them lexicographically.

gollark: He means to run mergesort/quicksort over them.