1dunst(1) Dunst Reference dunst(1)
2
6 dunst - A customizable and lightweight notification-daemon
7
9 dunst [-conf file] [-font font] [-geometry geom] [-format fmt] [-follow
10 mode] [-monitor n] [-history_length n] ...
11
13 Dunst is a highly configurable and lightweight notification daemon.
14
16 -h/--help
17 List all command line flags
18 -conf/-config file
20 Use alternative config file.
21 -v/--version
23 Print version information.
24 -print
26 Print notifications to stdout. This might be useful for logging,
27 setting up rules or using the output in other scripts.
28
30 An example configuration file is included (usually
31 /usr/share/dunst/dunstrc). To change the configuration, copy this file
32 to ~/.config/dunst/dunstrc and edit it accordingly.
33 The configuration is divided into sections in an ini-like format. The
35 'global' section contains most general settings while the 'shortcuts'
36 sections contains all keyboard configuration and the 'experimental'
37 section all the features that have not yet been tested thoroughly.
38 Any section that is not one of the above is assumed to be a rule, see
40 RULES for more details.
41 For backwards compatibility reasons the section name 'frame' is
43 considered bound and can't be used as a rule.
44 Command line
46 Each configuration option in the global section can be overridden from
47 the command line by adding a single dash in front of it's name. For
48 example the font option can be overridden by running
49 $ dunst -font "LiberationSans Mono 4"
51 Configuration options that take boolean values can only currently be
53 set to "true" through the command line via the same method. e.g.
54 $ dunst -shrink
56 This is a known limitation of the way command line parameters are
58 parsed and will be changed in the future.
59 Available settings per section:
61 Global section
63 monitor (default: 0)
64 Specifies on which monitor the notifications should be displayed
65 in, count starts at 0. See the follow setting.
66 follow (values: [none/mouse/keyboard] default: none)
68 Defines where the notifications should be placed in a multi-monitor
69 setup. All values except none override the monitor setting.
70 none
72 The notifications will be placed on the monitor specified by
73 the monitor setting.
74 mouse
76 The notifications will be placed on the monitor that the mouse
77 is currently in.
78 keyboard
80 The notifications will be placed on the monitor that contains
81 the window with keyboard focus.
82 geometry (format: [{width}][x{height}][+/-{x}[+/-{y}]], default:
84 "0x0+0-0")
85 The geometry of the window the notifications will be displayed in.
86 width
88 The width of the notification window in pixels. A negative
89 value sets the width to the screen width minus the absolute
90 value of the width. If the width is omitted then the window
91 expands to cover the whole screen. If it's 0 the window expands
92 to the width of the longest message being displayed.
93 height
95 The number of notifications that can appear at one time. When
96 this limit is reached any additional notifications will be
97 queued and displayed when the currently displayed ones either
98 time out or are manually dismissed. If indicate_hidden is true,
99 then the specified limit is reduced by 1 and the last
100 notification is a message informing how many hidden
101 notifications are waiting to be displayed. See the
102 indicate_hidden entry for more information.
103 The physical(pixel) height of the notifications vary depending
105 on the number of lines that need to be displayed.
106 See notification_height for changing the physical height.
108 x/y Respectively the horizontal and vertical offset in pixels from
110 the corner of the screen that the notification should be drawn
111 at. For the horizontal(x) offset, a positive value is measured
112 from the left of the screen while a negative one from the
113 right. For the vertical(y) offset, a positive value is measured
114 from the top while a negative from the bottom.
115 It's important to note that the positive and negative sign DOES
117 affect the position even if the offset is 0. For example, a
118 horizontal offset of +0 puts the notification on the left
119 border of the screen while a horizontal offset of -0 at the
120 right border. The same goes for the vertical offset.
121 indicate_hidden (values: [true/false], default: true)
123 If this is set to true, a notification indicating how many
124 notifications are not being displayed due to the notification limit
125 (see geometry) will be shown in place of the last notification
126 slot.
127 Meaning that if this is enabled the number of visible notifications
129 will be 1 less than what is specified in geometry, the last slot
130 will be taken by the hidden count.
131 shrink (values: [true/false], default: false)
133 Shrink window if it's smaller than the width. Will be ignored if
134 width is 0.
135 This is used mainly in order to have the shrinking benefit of
137 dynamic width (see geometry) while also having an upper bound on
138 how long a notification can get before wrapping.
139 transparency (default: 0)
141 A 0-100 range on how transparent the notification window should be,
142 with 0 being fully opaque and 100 invisible.
143 This setting will only work if a compositor is running.
145 notification_height (default: 0)
147 The minimum height of the notification window in pixels. If the
148 text and padding cannot fit in within the height specified by this
149 value, the height will be increased as needed.
150 separator_height (default: 2)
152 The height in pixels of the separator between notifications, if set
153 to 0 there will be no separating line between notifications.
154 padding (default: 0)
156 The distance in pixels from the content to the separator/border of
157 the window in the vertical axis
158 horizontal_padding (default: 0)
160 The distance in pixels from the content to the border of the window
161 in the horizontal axis
162 frame_width (default: 0)
164 Defines width in pixels of frame around the notification window.
165 Set to 0 to disable.
166 frame_color color (default: #888888)
168 Defines color of the frame around the notification window. See
169 COLORS.
170 separator_color (values: [auto/foreground/frame/#RRGGBB] default: auto)
172 Sets the color of the separator line between two notifications.
173 auto
175 Dunst tries to find a color that fits the rest of the
176 notification color scheme automatically.
177 foreground
179 The color will be set to the same as the foreground color of
180 the topmost notification that's being separated.
181 frame
183 The color will be set to the frame color of the notification
184 with the highest urgency between the 2 notifications that are
185 being separated.
186 anything else
188 Any other value is interpreted as a color, see COLORS
189 sort (values: [true/false], default: true)
191 If set to true, display notifications with higher urgency above the
192 others.
193 idle_threshold (default: 0)
195 Don't timeout notifications if user is idle longer than this time.
196 See TIME FORMAT for valid times.
197 Set to 0 to disable.
199 A client can mark a notification as transient to bypass this
201 setting and timeout anyway. Use a rule with 'set_transient = no' to
202 disable this behavior.
203 font (default: "Monospace 8")
205 Defines the font or font set used. Optionally set the size as a
206 decimal number after the font name and space. Multiple font
207 options can be separated with commas.
208 This options is parsed as a Pango font description.
210 line_height (default: 0)
212 The amount of extra spacing between text lines in pixels. Set to 0
213 to disable.
214 markup (values: [full/strip/no], default: no)
216 Defines how markup in notifications is handled.
217 It's important to note that markup in the format option will be
219 parsed regardless of what this is set to.
220 Possible values:
222 full
224 Allow a small subset of html markup in notifications
225 <b>bold</b>
227 <i>italic</i>
228 <s>strikethrough</s>
229 <u>underline</u>
230 For a complete reference see
232 <http://developer.gnome.org/pango/stable/PangoMarkupFormat.html>
233 strip
235 This setting is provided for compatibility with some broken
236 clients that send markup even though it's not enabled on the
237 server.
238 Dunst will try to strip the markup but the parsing is
240 simplistic so using this option outside of matching rules for
241 specific applications IS GREATLY DISCOURAGED.
242 See RULES
244 no Disable markup parsing, incoming notifications will be treated
246 as plain text. Dunst will not advertise that it can parse
247 markup if this is set as a global setting.
248 format (default: "%s %b")
250 Specifies how the various attributes of the notification should be
251 formatted on the notification window.
252 Regardless of the status of the markup setting, any markup tags
254 that are present in the format will be parsed. Note that because of
255 that, if a literal ampersand (&) is needed it needs to be escaped
256 as '&'
257 If '\n' is present anywhere in the format, it will be replaced with
259 a literal newline.
260 If any of the following strings are present, they will be replaced
262 with the equivalent notification attribute.
263 %a appname
265 %s summary
266 %b body
267 %i iconname (including its path)
268 %I iconname (without its path)
269 %p progress value ([ 0%] to [100%])
270 %n progress value without any extra characters
271 %% Literal %
272 If any of these exists in the format but hasn't been specified in
274 the notification (e.g. no icon has been set), the placeholders will
275 simply be removed from the format.
276 alignment (values: [left/center/right], default: left)
278 Defines how the text should be aligned within the notification.
279 show_age_threshold (default: -1)
281 Show age of message if message is older than this time. See TIME
282 FORMAT for valid times.
283 Set to -1 to disable.
285 word_wrap (values: [true/false], default: false)
287 Specifies how very long lines should be handled
288 If it's set to false, long lines will be truncated and ellipsized.
290 If it's set to true, long lines will be broken into multiple lines
292 expanding the notification window height as necessary for them to
293 fit.
294 ellipsize (values: [start/middle/end], default: middle)
296 If word_wrap is set to false, specifies where truncated lines
297 should be ellipsized.
298 ignore_newline (values: [true/false], default: false)
300 If set to true, replace newline characters in notifications with
301 whitespace.
302 stack_duplicates (values: [true/false], default: true)
304 If set to true, duplicate notifications will be stacked together
305 instead of being displayed separately.
306 Two notifications are considered duplicate if the name of the
308 program that sent it, summary, body, icon and urgency are all
309 identical.
310 hide_duplicates_count (values: [true/false], default: false)
312 Hide the count of stacked duplicate notifications.
313 show_indicators (values: [true/false], default: true)
315 Show an indicator if a notification contains actions and/or open-
316 able URLs. See ACTIONS below for further details.
317 icon_position (values: [left/right/off], default: off)
319 Defines the position of the icon in the notification window.
320 Setting it to off disables icons.
321 max_icon_size (default: 0)
323 Defines the maximum size in pixels for the icons. If the icon is
324 smaller than the specified value it won't be affected. If it's
325 larger then it will be scaled down so that the larger axis is
326 equivalent to the specified size.
327 Set to 0 to disable icon scaling. (default)
329 If icon_position is set to off, this setting is ignored.
331 icon_path (default:
333 "/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/")
334 Can be set to a colon-separated list of paths to search for icons
335 to use with notifications.
336 Dunst doesn't currently do any type of icon lookup outside of these
338 directories.
339 sticky_history (values: [true/false], default: true)
341 If set to true, notifications that have been recalled from history
342 will not time out automatically.
343 history_length (default: 20)
345 Maximum number of notifications that will be kept in history. After
346 that limit is reached, older notifications will be deleted once a
347 new one arrives. See HISTORY.
348 dmenu (default: "/usr/bin/dmenu")
350 The command that will be run when opening the context menu. Should
351 be either a dmenu command or a dmenu-compatible menu.
352 browser (default: "/usr/bin/firefox")
354 The command that will be run when opening a URL. The URL to be
355 opened will be appended to the end of the value of this setting.
356 always_run_script (values: [true/false] default: true]
358 Always run rule-defined scripts, even if the notification is
359 suppressed with format = "". See SCRIPTING.
360 title (default: "Dunst")
362 Defines the title of notification windows spawned by dunst.
363 (_NET_WM_NAME property). There should be no need to modify this
364 setting for regular use.
365 class (default: "Dunst")
367 Defines the class of notification windows spawned by dunst. (First
368 part of WM_CLASS). There should be no need to modify this setting
369 for regular use.
370 startup_notification (values: [true/false], default: false)
372 Display a notification on startup. This is usually used for
373 debugging and there shouldn't be any need to use this option.
374 verbosity (values: 'crit', 'warn', 'mesg', 'info', 'debug' default
376 'mesg')
377 Do not display log messages, which have lower precedence than
378 specified verbosity. This won't affect printing notifications on
379 the terminal. Use the '-print' option for this.
380 force_xinerama (values: [true/false], default: false)
382 Use the Xinerama extension instead of RandR for multi-monitor
383 support. This setting is provided for compatibility with older
384 nVidia drivers that do not support RandR and using it on systems
385 that support RandR is highly discouraged.
386 By enabling this setting dunst will not be able to detect when a
388 monitor is connected or disconnected which might break follow mode
389 if the screen layout changes.
390 corner_radius (default: 0)
392 Define the corner radius in pixels. A corner radius of 0 will
393 result in rectangular shaped notifications.
394 By enabling this setting the outer border and the frame will be
396 shaped. If you have multiple notifications, the whole window is
397 shaped, not every single notification.
398 To avoid the corners clipping the icon or text the corner radius
400 will be automatically lowered to half of the notification height if
401 it exceeds it.
402 mouse_left/middle/right_click (values:
404 [none/do_action/close_current/close_all])
405 Defines action of mouse click.
406 none
408 Don't do anything.
409 do_action (default for mouse_middle_click)
411 If the notification has exactly one action, or one is marked as
412 default, invoke it. If there are multiple and no default, open
413 the context menu.
414 close_current (default for mouse_left_click)
416 Close current notification.
417 close_all (default for mouse_right_click)
419 Close all notifications.
420 Shortcut section
422 Keyboard shortcuts are defined in the following format: "Modifier+key"
423 where the modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any
424 keyboard key.
425 close
427 command line flag: -key <key>
428 Specifies the keyboard shortcut for closing a notification.
430 close_all
432 command line flag: -all_key <key>
433 Specifies the keyboard shortcut for closing all currently displayed
435 notifications.
436 history
438 command line flag: -history_key <key>
439 Specifies the keyboard shortcut for recalling a single notification
441 from history.
442 context
444 command line flag: -context_key <key>
445 Specifies the keyboard shortcut that opens the context menu.
447 Urgency sections
449 The urgency sections work in a similar way to rules and can be used to
450 specify attributes for the different urgency levels of notifications
451 (low, normal, critical). Currently only the background, foreground,
452 timeout, frame_color and icon attributes can be modified.
453 The urgency sections are urgency_low, urgency_normal, urgency_critical
455 for low, normal and critical urgency respectively.
456 See the example configuration file for examples.
458 Additionally, you can override these settings via the following command
460 line flags:
461 Please note these flags may be removed in the future. See issue #328 in
463 the bug tracker for discussions (See REPORTING BUGS).
464 -li/ni/ci icon
466 Defines the icon for low, normal and critical notifications
467 respectively.
468 Where icon is a path to an image file containing the icon.
470 -lf/nf/cf color
472 Defines the foreground color for low, normal and critical
473 notifications respectively.
474 See COLORS for the value format.
476 -lb/nb/cb color
478 Defines the background color for low, normal and critical
479 notifications respectively.
480 See COLORS for the value format.
482 -lfr/nfr/cfr color
484 Defines the frame color for low, normal and critical notifications
485 respectively.
486 See COLORS for more information
488 -lto/nto/cto secs
490 Defines the timeout time for low, normal and critical notifications
491 respectively. See TIME FORMAT for valid times.
492
494 Dunst saves a number of notifications (specified by history_length) in
495 memory. These notifications can be recalled (i.e. redisplayed) by
496 pressing the history_key (see the shortcuts section), whether these
497 notifications will time out like if they have been just send depends on
498 the value of the sticky_history setting.
499 Past notifications are redisplayed in a first-in-last-out order,
501 meaning that pressing the history key once will bring up the most
502 recent notification that had been closed/timed out.
503
505 Rules allow the conditional modification of notifications. They are
506 defined by creating a section in the configuration file that has any
507 name that is not already used internally (i.e. any name other than
508 'global', 'experimental', 'frame', 'shortcuts', 'urgency_low',
509 'urgency_normal' and 'urgency_critical').
510 There are 2 parts in configuring a rule: Defining the filters that
512 control when a rule should apply and then the actions that should be
513 taken when the rule is matched.
514 filtering
516 Notifications can be matched for any of the following attributes:
517 "appname" (discouraged, see desktop_entry)
519 The name of the application as reported by the client. Be aware
520 that the name can often differ depending on the locale used.
521 "body"
523 The body of the notification
524 "category"
526 The category of the notification as defined by the notification
527 spec. See
528 https://developer.gnome.org/notification-spec/#categories
529 "desktop_entry"
531 GLib based applications export their desktop-entry name. In
532 comparison to the appname, the desktop-entry won't get
533 localized.
534 "icon"
536 The icon of the notification in the form of a file path. Can be
537 empty if no icon is available or a raw icon is used instead.
538 "match_transient"
540 Match if the notification has been declared as transient by the
541 client or by some other rule.
542 See "set_transient" for more details about this attribute.
544 "msg_urgency"
546 Matches the urgency of the notification as set by the client or
547 by some other rule.
548 "stack_tag"
550 Matches the stack tag of the notification as set by the client
551 or by some other rule.
552 See set_stack_tag for more information about stack tags.
554 "summary"
556 Matches the summary, 'title', of the notification.
557 "msg_urgency" is the urgency of the notification, it is named so to
559 not conflict with trying to modify the urgency.
560 Instead of the appname filter, it's recommended to use the
562 desktop_entry filter.
563 To define a matching rule simply assign the specified value to the
565 value that should be matched, for example:
566 appname="notify-send"
568 Matches only messages that were send via notify-send. If multiple
570 filter expressions are present, all of them have to match for the
571 rule to be applied (logical AND).
572 Shell-like globing is supported.
574 modifying
576 The following attributes can be overridden:
577 "background"
579 The background color of the notification. See COLORS for
580 possible values.
581 "foreground"
583 The background color of the notification. See COLORS for
584 possible values.
585 "format"
587 Equivalent to the "format" setting.
588 "frame_color"
590 The frame color color of the notification. See COLORS for
591 possible values.
592 "fullscreen"
594 One of show, delay, or pushback.
595 This attribute speicifies how notifications are handled if a
597 fullscreen window is focused. By default it's set to show so
598 notifications are being shown.
599 Other possible values are delay: Already shown notifications
601 are continued to be displayed until they are dismissed or time
602 out but new notifications will be held back and displayed when
603 the focus to the fullscreen window is lost.
604 Or pushback which is equivalent to delay with the difference
606 that already existing notifications are paused and hidden until
607 the focus to the fullscreen window is lost.
608 "new_icon"
610 Updates the icon of the notification, it should be a path to a
611 valid image.
612 "set_stack_tag"
614 Sets the stack tag for the notification, notifications with the
615 same (non-empty) stack tag will replace each-other so only the
616 newest one is visible. This can be useful for example in volume
617 or brightness notifications where only want one of the same
618 type visible.
619 The stack tag can be set by the client with the 'synchronous',
621 'private-synchronous' 'x-canonical-private-synchronous' or the
622 'x-dunst-stack-tag' hints.
623 "set_transient"
625 Sets whether the notification is considered transient.
626 Transient notifications will bypass the idle_threshold setting.
627 By default notifications are _not_ considered transient but
629 clients can set the value of this by specifying the 'transient'
630 hint when sending notifications.
631 "timeout"
633 Equivalent to the "timeout" setting in the urgency sections.
634 "urgency"
636 This sets the notification urgency.
637 IMPORTANT NOTE: This currently DOES NOT re-apply the attributes
639 from the urgency_* sections. The changed urgency will only be
640 visible in rules defined later. Use "msg_urgency" to match it.
641 "skip_display"
643 Setting this to true will prevent the notification from being
644 displayed initially but will be saved in history for later
645 viewing.
646 As with the filtering attributes, each one corresponds to the
648 respective notification attribute to be modified.
649 As with filtering, to make a rule modify an attribute simply assign
651 it in the rule definition.
652 If the format is set to an empty string, the notification will not
654 be suppressed.
655 SCRIPTING
657 Within rules you can specify a script to be run every time the rule is
658 matched by assigning the 'script' option to the name of the script to
659 be run.
660 When the script is called details of the notification that triggered it
662 will be passed via command line parameters in the following order:
663 appname, summary, body, icon, urgency.
664 Where icon is the absolute path to the icon file if there is one and
666 urgency is one of "LOW", "NORMAL" or "CRITICAL".
667 If the notification is suppressed, the script will not be run unless
669 always_run_scripts is set to true.
670 If '~/' occurs at the beginning of the script parameter, it will get
672 replaced by the users' home directory. If the value is not an absolute
673 path, the directories in the PATH variable will be searched for an
674 executable of the same name.
675
677 Colors are interpreted as X11 color values. This includes both verbatim
678 color names such as "Yellow", "Blue", "White", etc as well as #RGB and
679 #RRGGBB values.
680 NOTE: '#' is interpreted as a comment, to use it the entire value needs
682 to be in quotes like so: separator_color="#123456"
683 NOTIFY-SEND
685 dunst is able to get different colors for a message via notify-send.
686 In order to do that you have to add a hint via the -h option. The
687 progress value can be set with a hint, too.
688 notify-send -h string:fgcolor:#ff4444
690 notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h
691 string:frcolor:#44ff44
692 notify-send -h int:value:42 "Working ..."
693
695 Dunst allows notifiers (i.e.: programs that send the notifications) to
696 specify actions. Dunst has support for both displaying indicators for
697 these, and interacting with these actions.
698 If "show_indicators" is true and a notification has an action, an "(A)"
700 will be prepended to the notification format. Likewise, an "(U)" is
701 prepended to notifications with URLs. It is possible to interact with
702 notifications that have actions regardless of this setting, though it
703 may not be obvious which notifications HAVE actions.
704 The "context" keybinding is used to interact with these actions, by
706 showing a menu of possible actions. This feature requires "dmenu" or a
707 dmenu drop-in replacement present.
708 Alternatively, you can invoke an action with a middle click on the
710 notification. If there is exactly one associated action, or one is
711 marked as default, that one is invoked. If there are multiple, the
712 context menu is shown. The same applies to URLs when there are no
713 actions.
714
716 A time can be any decimal integer value suffixed with a time unit. If
717 no unit given, seconds ("s") is taken as default.
718 Time units understood by dunst are "ms", "s", "m", "h" and "d".
720 Example time: "1000ms" "10m"
722
724 Dunst can be paused by sending a notification with a summary of
725 "DUNST_COMMAND_PAUSE", resumed with a summary of "DUNST_COMMAND_RESUME"
726 and toggled with a summary of "DUNST_COMMAND_TOGGLE". Alternatively
727 you can send SIGUSR1 and SIGUSR2 to pause and unpause respectively. For
728 Example:
729 killall -SIGUSR1 dunst # pause
731 killall -SIGUSR2 dunst # resume
732 When paused dunst will not display any notifications but keep all
734 notifications in a queue. This can for example be wrapped around a
735 screen locker (i3lock, slock) to prevent flickering of notifications
736 through the lock and to read all missed notifications after returning
737 to the computer.
738
740 $XDG_CONFIG_HOME/dunst/dunstrc
741 -or-
743 $HOME/.config/dunst/dunstrc
745
747 Written by Sascha Kruse <knopwob@googlemail.com>
748
750 Bugs and suggestions should be reported on GitHub at
751 https://github.com/dunst-project/dunst/issues
752
754 Copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing
755 information)
756 If you feel that copyrights are violated, please send me an email.
758
760 dwm(1), dmenu(1), twmn(1), notify-send(1)
7611.4.1 2020-01-28 dunst(1)