dunst(1)

📦
version 1.13.2 · 11 versions
, in fedora 43, fedora 44

🌸 dunst — the manual page, but make it cute 🌸

okay bestie, welcome to dunst(1), aka the Dunst Reference, aka the glow-up doc for your notification situation. no cap, this is genuinely one of the most useful little daemons out there and i'm gonna walk you through every single flag like we're texting at 2am. 💖

✨ NAME ✨

dunst — a customizable and lightweight notification-daemon 🦋

✨ SYNOPSIS ✨

dunst [--config FILE] [--verbosity v] [--print] [--startup_notification]

that's it, that's the whole vibe. periodt. 💅

✨ DESCRIPTION ✨

Dunst is a highly configurable and lightweight notification daemon. literally iconic, it just sits there being small and pretty and catching all your notifications. 🎀

🌈 Autostarting dunst

ok so on most installations, dunst should be able to automatically be started by D-Bus whenever a notification gets sent. super convenient, right? but — and this is the important part — this is not recommended when you have multiple notification daemons installed, because D-Bus will not know which one to start. imagine the chaos. 😭 so yeah, don't do that in that case.

other ways of autostarting dunst include:

  • starting dunst with your desktop environment or window manager's autostart functionality
  • via the provided systemd service

pick your fighter. 🫶

✨ COMMAND LINE OPTIONS ✨

  • -h/-help/--help — lists all the command line flags. your little cheat sheet bestie 💖
  • -conf/-config/--config FILE — use an alternative config file. this disables the search for other config files, so it's the one and only. if it cannot be opened, dunst will issue a warning and fall back on its internal defaults. (hint: dunst -conf - </dev/null can be used to enforce the defaults, i.e. for testing) 🧚
  • -v/-version/--version — print version information. ✨
  • -verbosity/--verbosity (values: 'crit', 'warn', 'mesg', 'info', 'debug' — default 'mesg') — do not display log messages which have lower precedence than the specified verbosity. heads up tho: this won't affect printing notifications on the terminal. use the '-print' option for that. 👑
  • -print/--print — print notifications to stdout. this might be useful for logging, setting up rules or using the output in other scripts. lowkey a power move 🔥
  • -startup_notification/--startup_notification — display a notification on startup. say hi 👋

✨ CONFIGURATION ✨

a default configuration file is included (usually /etc/xdg/dunst/dunstrc) and it serves as the least important configuration file. note: this was previously /usr/share/dunst/dunstrc. you can edit this file to change the system-wide defaults, or copy it to a more important location to override its settings. see the FILES section for more details on where dunst searches for its configuration files and how settings get applied. 🗂️

see dunst(5) for all possible settings. (yes there are a lot. we love a thorough queen.)

🌸 NOTIFY-SEND HINTS

Dunst is able to get different colors for a message via notify-send. in order to do that you have to add a hint via the -h option. the progress value can be set with a hint too. 💅

see dunst(5) for the list of accepted hints.

some examples:

notify-send -h string:fgcolor:#ff4444

notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h string:frcolor:#44ff44

notify-send -h int:value:42 "Working ..."

✨ MISCELLANEOUS ✨

Dunst can be paused via the dunstctl set-paused true command. to unpause dunst use dunstctl set-paused false. another way is to send SIGUSR1 and SIGUSR2 to pause and unpause respectively.

⚠️ pausing using dunstctl is recommended over using signals, because the meaning of the signals isn't stable and might change in the future. so like... use dunstctl, bestie, it's the safe choice. 🫶

when paused, dunst won't display any notifications, but keeps all notifications in a queue. this can for example be wrapped around a screen locker (i3lock, slock) to prevent flickering of notifications through the lock, and to read all missed notifications after returning to the computer. obsessed with this feature actually. 🌈

✨ FILES ✨

these are the base directories dunst searches for configuration files in, descending order of importance:

  • $XDG_CONFIG_HOME — this is the most important directory. ("$HOME/.config" if unset or empty)
  • $XDG_CONFIG_DIRS — this, like $PATH for instance, is a :-separated list of base directories in descending order of importance. (/etc/xdg if unset or empty)

Dunst will search these directories for the following relative file paths:

  • dunst/dunstrc — this is the base config and as such the least important in a particular base directory.
  • dunst/dunstrc.d/*.conf — these are "drop-ins" (mind the ".d" suffix of the directory). they are more important than the base dunstrc in the parent directory, as they are considered to be small snippets to override settings. the last in lexical order is the most important one, so you can easily change the order by renaming them. a common approach to naming drop-ins is to prefix them with numbers, i.e.:
00-least-important.conf
01-foo.conf
20-bar.conf
99-most-important.conf

only files with the .conf suffix will be read. 📝

only settings from the last base config the corresponding drop-ins get applied. so if a dunstrc is first found in ~/.config/dunst/dunstrc, drop-ins will be searched in ~/.config/dunst/dunstrc.d/*. settings in more important files override those in less important ones.

if you want to dynamically change the config you can simply use the command dunstctl reload to load the modified files. see more in dunst(5). 🔄

✨ REPORTING BUGS ✨

bugs and suggestions should be reported on GitHub at https://github.com/dunst-project/dunst/issues — pls be nice and detailed, the maintainers are doing great work 💖

Copyright 2011-2014 Sascha Kruse

Copyright 2014-2026 Dunst contributors

Dunst is released under the BSD 3-Clause License, see LICENSE for more information.

if you feel that copyrights are violated, please send an email to the maintainers. 🫶

✨ SEE ALSO ✨

dunst(5), dunstctl(1), dmenu(1), notify-send(1), dunstify(1) — go read the rest of the family, they're all serving 💅

and that's the whole page bestie!! 🎀 this one's from Dunst Reference, version 1.13.2, dated 2026-03-19, manual section dunst(1). go forth and get notified, you absolute main character. 💖✨🦋

📦 where this page comes from