In this article
A notification should be visible and readable without taking over the desktop. Dunst is a lightweight notification service that suits custom Linux desktops particularly well. Its settings live in a local text file.
My dunstrc in the Cthulhu repository is this guide's starting point. The file documents a published configuration; it does not establish that Dunst is active in every current session. Full desktops such as Plasma have their own notification implementation.
Which program displays a notification?
An application sends a message over the session bus to the notification service. Dunst draws the window, applies appearance settings and rules, and can show older messages again. The browser or messenger remains responsible for the content.
Before testing, check whether you actually use Dunst:
dunstctl debug
This command tries to contact Dunst and detect common communication problems. If another service owns notifications, do not simply launch a second daemon and replace your desktop's existing service. The exercise below assumes a running Dunst session. Setting up a new service depends on your desktop's startup mechanism and package documentation.
Read the sections of my file
My global section contains:
[global]
frame_color = "#8aadf4"
separator_color = "#8aadf4"
font = JetBrainsMono Nerd Font 10
corner_radius = 8
[global] holds general settings. The border and separator use light blue; the font value combines a family name and size. Rounded corners affect the notification window's appearance.
The file then has three urgency sections. My normal background is dark, while critical messages use pink with dark text. These are different colours from the Gruvbox palette in my X1 Gruvnode profile.
| Section | Purpose |
|---|---|
[urgency_low] |
Lower-priority notifications |
[urgency_normal] |
Ordinary notifications |
[urgency_critical] |
Critical notifications |
The application initially chooses urgency, so colour alone cannot reliably establish a message's importance. My published file does not include personal position, timeout or application rules. The additions below are original teaching examples.
Create a separate exercise file
Make a new directory:
mkdir -p ~/dunst-tutorial
Save this as ~/dunst-tutorial/dunstrc. The offset syntax follows current Dunst versions; check the installed manual if your version is older:
[global]
font = monospace 11
origin = top-right
offset = (20, 40)
width = 320
frame_width = 2
frame_color = "#8aadf4"
corner_radius = 8
[urgency_low]
background = "#181926"
foreground = "#cad3f5"
timeout = 4s
[urgency_normal]
background = "#1e2030"
foreground = "#cad3f5"
timeout = 8s
[urgency_critical]
background = "#ed8796"
foreground = "#181926"
timeout = 0
A current running instance can load this specific file:
dunstctl reload ~/dunst-tutorial/dunstrc
This temporarily affects real notifications in the session too. It does not overwrite your regular configuration file. Later, use dunstctl reload without a filename to return to the files selected when Dunst originally started.
Test position and timeouts
Send an ordinary exercise message with notify-send, available for example through libnotify packages:
notify-send --app-name=DunstTutorial --urgency=normal "Dunst test" "Check position and readability"
The message should appear at the top right with space from the edges. origin selects a reference point; offset moves the notification away from it. Change only the vertical offset first, then reload.
timeout describes the requested display duration. Applications can supply their own timeout values; rules and Dunst settings determine which value takes effect. With timeout = 0, Dunst's setting keeps the message visible until dismissed. Test critical urgency separately:
notify-send --app-name=DunstTutorial --urgency=critical "Dunst test" "Dismiss this exercise message deliberately"
Dismiss the message using the available Dunst controls or:
dunstctl close
Add a rule for the test application name
Append a named section:
[tutorial]
appname = DunstTutorial
background = "#285577"
foreground = "#ffffff"
After reloading, these colours affect only messages carrying that application name. Send the ordinary test message again and compare. Multiple filters within a rule must all match; rule order and later settings can influence the result.
For real applications, a stable desktop_entry filter is often preferable to a translated application name. The exercise deliberately supplies its own name so you can control the match. A messenger's visible window title is not necessarily the correct filter value.
Troubleshoot and return to your original settings
If nothing appears, begin with dunstctl debug, pause state and notification-service ownership. If colours or duration are wrong, inspect the loaded file and rules. Under Wayland, global keyboard bindings usually belong to the compositor; an old X11 shortcut setting may have no effect there.
Return to the original configuration:
dunstctl reload
Send a normal message afterwards. Once satisfied, transfer selected values with your editor into the regular file, usually ~/.config/dunst/dunstrc. Current versions also support drop-in files that can override settings.
Privacy and references
Notifications may contain names, message content or one-time codes. A local daemon does not make a shared screenshot automatically harmless. Additional actions and scripts need the same scrutiny as shell commands; this tutorial requires none.
- Checked Cthulhu dunstrc.
- Dunst configuration reference: position, urgency and rules.
- dunstctl manual: reloading and controls.
- Dunst configuration search: base files and drop-ins.
Configuration and references checked on 8 October 2026.