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 Transient notifications will ignore this setting and timeout
201 anyway. Use a rule overwriting 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 an ellipsised.
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 force_xinerama (values: [true/false], default: false)
376 Use the Xinerama extension instead of RandR for multi-monitor
377 support. This setting is provided for compatibility with older
378 nVidia drivers that do not support RandR and using it on systems
379 that support RandR is highly discouraged.
380 By enabling this setting dunst will not be able to detect when a
382 monitor is connected or disconnected which might break follow mode
383 if the screen layout changes.
384 Shortcut section
386 Keyboard shortcuts are defined in the following format: "Modifier+key"
387 where the modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any
388 keyboard key.
389 close
391 command line flag: -key <key>
392 Specifies the keyboard shortcut for closing a notification.
394 close_all
396 command line flag: -all_key <key>
397 Specifies the keyboard shortcut for closing all currently displayed
399 notifications.
400 history
402 command line flag: -history_key <key>
403 Specifies the keyboard shortcut for recalling a single notification
405 from history.
406 context
408 command line flag: -context_key <key>
409 Specifies the keyboard shortcut that opens the context menu.
411 Urgency sections
413 The urgency sections work in a similar way to rules and can be used to
414 specify attributes for the different urgency levels of notifications
415 (low, normal, critical). Currently only the background, foreground,
416 timeout, frame_color and icon attributes can be modified.
417 The urgency sections are urgency_low, urgency_normal, urgency_critical
419 for low, normal and critical urgency respectively.
420 See the example configuration file for examples.
422 Additionally, you can override these settings via the following command
424 line flags:
425 Please note these flags may be removed in the future. See issue #328 in
427 the bug tracker for discussions (See REPORTING BUGS).
428 -li/ni/ci icon
430 Defines the icon for low, normal and critical notifications
431 respectively.
432 Where icon is a path to an image file containing the icon.
434 -lf/nf/cf color
436 Defines the foreground color for low, normal and critical
437 notifications respectively.
438 See COLORS for the value format.
440 -lb/nb/cb color
442 Defines the background color for low, normal and critical
443 notifications respectively.
444 See COLORS for the value format.
446 -lfr/nfr/cfr color
448 Defines the frame color for low, normal and critical notifications
449 respectively.
450 See COLORS for more information
452 -lto/nto/cto secs
454 Defines the timeout time for low, normal and critical notifications
455 respectively. See TIME FORMAT for valid times.
456
458 Dunst saves a number of notifications (specified by history_length) in
459 memory. These notifications can be recalled (i.e. redesiplayed) by
460 pressing the history_key (see the shortcuts section), whether these
461 notifications will time out like if they have been just send depends on
462 the value of the sticky_history setting.
463 Past notifications are redisplayed in a first-in-last-out order,
465 meaning that pressing the history key once will bring up the most
466 recent notification that had been closed/timed out.
467
469 Rules allow the conditional modification of notifications. They are
470 defined by creating a section in the configuration file that has any
471 name that is not already used internally (i.e. any name other than
472 'global', 'experimental', 'frame', 'shortcuts', 'urgency_low',
473 'urgency_normal' and 'urgency_critical').
474 There are 2 parts in configuring a rule: Defining the filters that
476 control when a rule should apply and then the actions that should be
477 taken when the rule is matched.
478 filtering
480 Notifications can be matched for any of the following attributes:
481 appname, summary, body, icon, category, match_transient and
482 msg_urgency where each is the respective notification attribute to
483 be matched and 'msg_urgency' is the urgency of the notification, it
484 is named so to not conflict with trying to modify the urgency.
485 To define a matching rule simply assign the specified value to the
487 value that should be matched, for example:
488 appname="notify-send"
490 Matches only messages that were send via notify-send. If multiple
492 filter expressions are present, all of them have to match for the
493 rule to be applied (logical AND).
494 Shell-like globing is supported.
496 modifying
498 The following attributes can be overridden: timeout, urgency,
499 foreground, background, new_icon, set_transient, format where, as
500 with the filtering attributes, each one corresponds to the
501 respective notification attribute to be modified.
502 As with filtering, to make a rule modify an attribute simply assign
504 it in the rule definition.
505 If the format is set to an empty string, the notification will not
507 be suppressed.
508 SCRIPTING
510 Within rules you can specify a script to be run every time the rule is
511 matched by assigning the 'script' option to the name of the script to
512 be run.
513 When the script is called details of the notification that triggered it
515 will be passed via command line parameters in the following order:
516 appname, summary, body, icon, urgency.
517 Where icon is the absolute path to the icon file if there is one and
519 urgency is one of "LOW", "NORMAL" or "CRITICAL".
520 If the notification is suppressed, the script will not be run unless
522 always_run_scripts is set to true.
523 If '~/' occurs at the beginning of the script parameter, it will get
525 replaced by the users' home directory. If the value is not an absolute
526 path, the directories in the PATH variable will be searched for an
527 executable of the same name.
528
530 Colors are interpreted as X11 color values. This includes both verbatim
531 color names such as "Yellow", "Blue", "White", etc as well as #RGB and
532 #RRGGBB values.
533 NOTE: '#' is interpreted as a comment, to use it the entire value needs
535 to be in quotes like so: separator_color="#123456"
536 NOTIFY-SEND
538 dunst is able to get different colors for a message via notify-send.
539 In order to do that you have to add a hint via the -h option. The
540 progress value can be set with a hint, too.
541 notify-send -h string:fgcolor:#ff4444
543 notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444
544 notify-send -h int:value:42 "Working ..."
545
547 Dunst allows notifiers (i.e.: programs that send the notifications) to
548 specify actions. Dunst has support for both displaying indicators for
549 these, and interacting with these actions.
550 If "show_indicators" is true and a notification has an action, an "(A)"
552 will be prepended to the notification format. Likewise, an "(U)" is
553 preneded to notifications with URLs. It is possible to interact with
554 notifications that have actions regardless of this setting, though it
555 may not be obvious which notifications HAVE actions.
556 The "context" keybinding is used to interact with these actions, by
558 showing a menu of possible actions. This feature requires "dmenu" or a
559 dmenu drop-in replacement present.
560 Alternatively, you can invoke an action with a middle click on the
562 notification. If there is exactly one associated action, or one is
563 marked as default, that one is invoked. If there are multiple, the
564 context menu is shown. The same applies to URLs when there are no
565 actions.
566
568 A time can be any decimal integer value suffixed with a time unit. If
569 no unit given, seconds ("s") is taken as default.
570 Time units understood by dunst are "ms", "s", "m", "h" and "d".
572 Example time: "1000ms" "10m"
574
576 Dunst can be paused by sending a notification with a summary of
577 "DUNST_COMMAND_PAUSE" and resumed with a summary of
578 "DUNST_COMMAND_RESUME". Alternatively you can send SIGUSR1 and SIGUSR2
579 to pause and unpause respectively. For Example:
580 killall -SIGUSR1 dunst # pause
582 killall -SIGUSR2 dunst # resume
583 When paused dunst will not display any notifications but keep all
585 notifications in a queue. This can for example be wrapped around a
586 screen locker (i3lock, slock) to prevent flickering of notifications
587 through the lock and to read all missed notifications after returning
588 to the computer.
589
591 $XDG_CONFIG_HOME/dunst/dunstrc
592 -or-
594 $HOME/.config/dunst/dunstrc
596
598 Written by Sascha Kruse <knopwob@googlemail.com>
599
601 Bugs and suggestions should be reported on GitHub at
602 https://github.com/dunst-project/dunst/issues
603
605 Copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing
606 information)
607 If you feel that copyrights are violated, please send me an email.
609
611 dwm(1), dmenu(1), twmn(1), notify-send(1)
6121.3.2 2018-05-06 dunst(1)