Skip to main content

​
Dunst Notification Daemon

Dunst is a lightweight and customizable notification daemon for Linux, providing desktop notifications with extensive configuration options.

​
Overview

Configuration file: ~/.config/dunst/dunstrc Dunst displays notifications with customizable appearance, behavior, and urgency levels.

​
Display Configuration

​
Basic Display Settings

[global]
    monitor = 0
    follow = keyboard
    geometry = "350x5-4+24"
    indicate_hidden = yes
    shrink = yes

​
Geometry Format

The geometry setting uses the format: WIDTHxHEIGHT-X+Y 
geometry = "350x5-4+24"
  • 350 - Width in pixels
  • x5 - Show up to 5 notifications
  • -4 - 4 pixels from right edge (negative = from right)
  • +24 - 24 pixels from top edge (positive = from top)
Position Examples:
# Top-right corner
geometry = "300x5-10+30"

# Top-left corner
geometry = "300x5+10+30"

# Bottom-right corner
geometry = "300x5-10-30"

# Centered at top
geometry = "300x5-0+30"

​
Monitor and Follow Settings

monitor = 0
follow = keyboard
follow = keyboard displays notifications on the monitor with keyboard focus. Options: none, mouse, keyboard

​
Notification Appearance

​
Size and Spacing

transparency = 0
notification_height = 40
separator_height = 4
padding = 10
horizontal_padding = 8

​
Frame and Borders

frame_width = 0
frame_color = "#ffffff00"
separator_color = frame
corner_radius = 2
ParameterValueDescription
transparency0-100Window transparency level
notification_height40Minimum notification height
separator_height4Space between notifications
corner_radius2Border radius in pixels

​
Text Configuration

​
Font and Formatting

font = Monospace 12
line_height = 0
markup = full
format = "<b>%s</b>\n%b"
alignment = left
vertical_alignment = center

​
Format String

format = "<b>%s</b>\n%b"
  • %a - Application name
  • %s - Summary (title)
  • %b - Body text
  • %i - Icon path
  • %I - Icon name
  • %p - Progress value (if provided)
  • %n - Progress value without ”%” sign
  • %% - Literal %
Examples:
# Bold title, normal body
format = "<b>%s</b>\n%b"

# Show app name in italics
format = "<i>%a</i>: <b>%s</b>\n%b"

# Include progress bar
format = "<b>%s</b> %p\n%b"

​
Text Processing

show_age_threshold = 60
word_wrap = yes
ellipsize = middle
ignore_newline = no
stack_duplicates = true
hide_duplicate_count = false
show_indicators = yes
ellipsize = middle truncates long text in the middle, preserving start and end. Options: start, middle, end

​
Icon Configuration

icon_position = left
min_icon_size = 0
max_icon_size = 32
icon_path = /usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/

​
Icon Settings

1
Set icon position
2
icon_position = left  # left, right, top, off
3
Configure icon size
4
min_icon_size = 0
max_icon_size = 32
5
Add icon theme paths
6
icon_path = /usr/share/icons/Papirus/16x16/status/:/usr/share/icons/Papirus/16x16/apps/

​
History and Behavior

​
History Settings

sticky_history = yes
history_length = 20

​
Sorting and Timing

sort = yes
idle_threshold = 120
  • sticky_history: Keep notifications in history when dismissed
  • history_length: Maximum notifications to store
  • sort: Sort notifications by urgency
  • idle_threshold: Seconds before considering user idle
Idle behavior:
  • Notifications are suppressed when idle
  • They appear when you return
  • Prevents notification spam while away

​
Keyboard Shortcuts

[shortcuts]
    close = ctrl+space
    close_all = ctrl+shift+space
    history = ctrl+grave
    context = ctrl+shift+period

​
Available Shortcuts

ShortcutAction
ctrl+spaceClose current notification
ctrl+shift+spaceClose all notifications
ctrl+grave (backtick)Show notification history
ctrl+shift+periodOpen context menu
Customize shortcuts by changing the keybindings in the [shortcuts] section.

​
Mouse Actions

mouse_left_click = close_all
mouse_middle_click = do_action, close_current
mouse_right_click = close_current

​
Mouse Button Options

  • none - Do nothing
  • do_action - Execute notification action
  • close_current - Close clicked notification
  • close_all - Close all notifications
  • context - Open context menu
  • context_all - Open context menu for all
Example configurations:
# Left click to execute action
mouse_left_click = do_action, close_current

# Right click for context menu
mouse_right_click = context

# Middle click to close all
mouse_middle_click = close_all

​
Urgency Levels

​
Low Urgency

[urgency_low]
    background = "#222222"
    foreground = "#888888"
    timeout = 5

​
Normal Urgency

[urgency_normal]
    background = "#49445A"
    foreground = "#ffffff"
    timeout = 5

​
Critical Urgency

[urgency_critical]
    background = "#FF8383"
    foreground = "#ffffff"
    frame_color = "#FF8383"
    timeout = 0
Critical notifications have timeout = 0, meaning they never auto-dismiss. They must be manually closed.

​
Timeout Values

TimeoutBehavior
0Never timeout (requires manual dismiss)
>0Timeout after N seconds
-1Use default timeout

​
Advanced Configuration

​
Application-Specific Rules

Add custom sections for per-application settings: 
# Firefox notifications
[firefox]
    appname = Firefox
    urgency = normal
    background = "#2B2B2B"
    foreground = "#FFFFFF"
    timeout = 10

# Spotify notifications
[spotify]
    appname = Spotify
    urgency = low
    background = "#1DB954"
    foreground = "#000000"
    timeout = 5
    format = "🎵 <b>%s</b>\n%b"

​
Rule Matching

You can match notifications by:
  • appname - Application name
  • summary - Notification title
  • body - Notification body text
  • icon - Icon name or path
  • category - Notification category
  • msg_urgency - Urgency level
  • stack_tag - Stack tag for grouping
  • desktop_entry - Desktop entry name
Example rules:
# Hide notifications matching "foo"
[ignore-foo]
    summary = "*foo*"
    format = ""

# Custom format for specific app
[custom-app]
    desktop_entry = "myapp"
    format = "📱 %s: %b"
    background = "#333333"

# Low urgency for specific body text
[downgrade-urgency]
    body = "*not important*"
    urgency = low

​
Script Execution

Run scripts when notifications match: 
[run-script]
    summary = "*backup*"
    script = ~/.config/dunst/scripts/backup-notification.sh
Script receives arguments: 
#!/bin/bash
# $1 = appname
# $2 = summary
# $3 = body
# $4 = icon
# $5 = urgency

echo "Notification from $1: $2" >> ~/notification.log

​
Fullscreen Behavior

[fullscreen_delay]
    fullscreen = delay
  • show - Always show notifications
  • delay - Show only if no fullscreen window
  • pushback - Hide when entering fullscreen
Per-urgency override:
[fullscreen_show_critical]
    msg_urgency = critical
    fullscreen = show

​
Starting Dunst

​
Auto-start with i3

Add to ~/.config/i3/config: 
exec_always --no-startup-id dunst

​
Manual Start

# Start dunst
dunst

# Start with specific config
dunst -config ~/.config/dunst/dunstrc

# Print config and exit (for debugging)
dunst -print

​
Testing Notifications

1
Send test notification
2
notify-send "Test" "This is a test notification"
3
Test with urgency
4
notify-send -u low "Low" "Low urgency"
notify-send -u normal "Normal" "Normal urgency"
notify-send -u critical "Critical" "Critical urgency"
5
Test with icon
6
notify-send -i dialog-information "Info" "With icon"
7
Test with timeout
8
notify-send -t 3000 "Short" "3 second timeout"

​
Notification Control

​
Using dunstctl

# Close last notification
dunstctl close

# Close all notifications
dunstctl close-all

# Show notification history
dunstctl history-pop

# Toggle pause
dunstctl set-paused toggle

# Check if paused
dunstctl is-paused

# Get notification count
dunstctl count

​
i3 Integration

Add to i3 config for quick control: 
# Toggle pause notifications
bindsym $mod+n exec --no-startup-id dunstctl set-paused toggle

# Close all notifications
bindsym $mod+Shift+n exec --no-startup-id dunstctl close-all

# Show history
bindsym $mod+Ctrl+n exec --no-startup-id dunstctl history-pop

​
Styling Tips

​
Modern Dark Theme

[urgency_low]
    background = "#1e1e2e"
    foreground = "#cdd6f4"
    timeout = 5

[urgency_normal]
    background = "#313244"
    foreground = "#cdd6f4"
    frame_color = "#89b4fa"
    timeout = 7

[urgency_critical]
    background = "#f38ba8"
    foreground = "#1e1e2e"
    frame_color = "#f38ba8"
    timeout = 0

​
Minimal Style

[global]
    frame_width = 1
    corner_radius = 4
    padding = 12
    horizontal_padding = 12
    font = Sans 10
    format = "%s\n%b"

​
Progress Bar Notifications

[global]
    format = "<b>%s</b> %p\n%b"
    progress_bar = true
    progress_bar_height = 10
    progress_bar_frame_width = 1
    progress_bar_min_width = 150
    progress_bar_max_width = 300

​
Troubleshooting

1
Check if Dunst is running
2
ps aux | grep dunst
3
Kill and restart
4
killall dunst
dunst &
5
Test configuration
6
dunst -print
7
View debug output
8
dunst -verbosity debug

​
Common Issues

Check:
  1. Dunst is running: pgrep dunst
  2. No other notification daemons: pgrep -a notification
  3. Test with: notify-send "Test" "Message"
  4. Check config syntax: dunst -print
Solutions:
  1. Install icon theme:
sudo pacman -S papirus-icon-theme
  1. Set correct icon path:
icon_path = /usr/share/icons/Papirus/16x16/
  1. Verify icon exists:
ls /usr/share/icons/Papirus/
Check:
  1. No conflicting i3 bindings
  2. Dunst has focus when pressing shortcuts
  3. Try different key combinations
  4. Check with: xbindkeys -mk

​
Experimental Features

[experimental]
    per_monitor_dpi = false
Experimental features may be unstable. Enable with caution and refer to Dunst documentation for details.

​
Additional Configuration

​
Browser Integration

browser = /usr/bin/firefox -new-tab
Opens URLs in notifications with the specified browser.

​
DMenu Integration

dmenu = /usr/bin/dmenu -p dunst:
Uses dmenu or rofi for action selection: 
dmenu = /usr/bin/rofi -dmenu -p "Select action:"

​
Startup Notification

startup_notification = false
Disables the startup notification when Dunst launches.

​
Summary

Dunst provides a lightweight, highly customizable notification system perfect for i3 window manager. Key features include:
  • Urgency-based styling for different notification types
  • Keyboard shortcuts for quick control
  • History for missed notifications
  • Per-application rules for custom behavior
  • Minimal resource usage ideal for tiling WMs

Build docs developers (and LLMs) love

Get started for freeTalk to us