1dunst(1)                        Dunst Reference                       dunst(1)
2
3
4

NAME

6       dunst - A customizable and lightweight notification-daemon
7

SYNOPSIS

9       dunst [-conf file] [-font font] [-geometry geom] [-format fmt] [-follow
10       mode] [-monitor n] [-history_length n] ...
11

DESCRIPTION

13       Dunst is a highly configurable and lightweight notification daemon.
14

COMMAND LINE OPTIONS

16       -h/--help
17           List all command line flags
18
19       -conf/-config file
20           Use alternative config file.
21
22       -v/--version
23           Print version information.
24
25       -print
26           Print notifications to stdout. This might be useful for logging,
27           setting up rules or using the output in other scripts.
28

CONFIGURATION

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
34       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
39       Any section that is not one of the above is assumed to be a rule, see
40       RULES for more details.
41
42       For backwards compatibility reasons the section name 'frame' is
43       considered bound and can't be used as a rule.
44
45   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
50           $ dunst -font "LiberationSans Mono 4"
51
52       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
55           $ dunst -shrink
56
57       This is a known limitation of the way command line parameters are
58       parsed and will be changed in the future.
59
60       Available settings per section:
61
62   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
67       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
71           none
72               The notifications will be placed on the monitor specified by
73               the monitor setting.
74
75           mouse
76               The notifications will be placed on the monitor that the mouse
77               is currently in.
78
79           keyboard
80               The notifications will be placed on the monitor that contains
81               the window with keyboard focus.
82
83       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
87           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
94           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
104               The physical(pixel) height of the notifications vary depending
105               on the number of lines that need to be displayed.
106
107               See notification_height for changing the physical height.
108
109           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
116               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
122       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
128           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
132       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
136           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
140       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
144           This setting will only work if a compositor is running.
145
146       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
151       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
155       padding (default: 0)
156           The distance in pixels from the content to the separator/border of
157           the window in the vertical axis
158
159       horizontal_padding (default: 0)
160           The distance in pixels from the content to the border of the window
161           in the horizontal axis
162
163       frame_width (default: 0)
164           Defines width in pixels of frame around the notification window.
165           Set to 0 to disable.
166
167       frame_color color (default: #888888)
168           Defines color of the frame around the notification window. See
169           COLORS.
170
171       separator_color (values: [auto/foreground/frame/#RRGGBB] default: auto)
172           Sets the color of the separator line between two notifications.
173
174           auto
175               Dunst tries to find a color that fits the rest of the
176               notification color scheme automatically.
177
178           foreground
179               The color will be set to the same as the foreground color of
180               the topmost notification that's being separated.
181
182           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
187           anything else
188               Any other value is interpreted as a color, see COLORS
189
190       sort (values: [true/false], default: true)
191           If set to true, display notifications with higher urgency above the
192           others.
193
194       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
198           Set to 0 to disable.
199
200           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
204       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
209           This options is parsed as a Pango font description.
210
211       line_height (default: 0)
212           The amount of extra spacing between text lines in pixels. Set to 0
213           to disable.
214
215       markup (values: [full/strip/no], default: no)
216           Defines how markup in notifications is handled.
217
218           It's important to note that markup in the format option will be
219           parsed regardless of what this is set to.
220
221           Possible values:
222
223           full
224               Allow a small subset of html markup in notifications
225
226                   <b>bold</b>
227                   <i>italic</i>
228                   <s>strikethrough</s>
229                   <u>underline</u>
230
231               For a complete reference see
232               <http://developer.gnome.org/pango/stable/PangoMarkupFormat.html>
233
234           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
239               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
243               See RULES
244
245           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
249       format (default: "%s %b")
250           Specifies how the various attributes of the notification should be
251           formatted on the notification window.
252
253           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 '&amp;'
257
258           If '\n' is present anywhere in the format, it will be replaced with
259           a literal newline.
260
261           If any of the following strings are present, they will be replaced
262           with the equivalent notification attribute.
263
264           %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
273           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
277       alignment (values: [left/center/right], default: left)
278           Defines how the text should be aligned within the notification.
279
280       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
284           Set to -1 to disable.
285
286       word_wrap (values: [true/false], default: false)
287           Specifies how very long lines should be handled
288
289           If it's set to false, long lines will be truncated and ellipsized.
290
291           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
295       ellipsize (values: [start/middle/end], default: middle)
296           If word_wrap is set to false, specifies where truncated lines
297           should be ellipsized.
298
299       ignore_newline (values: [true/false], default: false)
300           If set to true, replace newline characters in notifications with
301           whitespace.
302
303       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
307           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
311       hide_duplicates_count (values: [true/false], default: false)
312           Hide the count of stacked duplicate notifications.
313
314       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
318       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
322       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
328           Set to 0 to disable icon scaling. (default)
329
330           If icon_position is set to off, this setting is ignored.
331
332       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
337           Dunst doesn't currently do any type of icon lookup outside of these
338           directories.
339
340       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
344       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
349       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
353       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
357       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
361       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
366       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
371       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
375       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
381       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
387           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
391       corner_radius (default: 0)
392           Define the corner radius in pixels. A corner radius of 0 will
393           result in rectangular shaped notifications.
394
395           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
399           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
403       mouse_left/middle/right_click (values:
404       [none/do_action/close_current/close_all])
405           Defines action of mouse click.
406
407           none
408               Don't do anything.
409
410           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
415           close_current (default for mouse_left_click)
416               Close current notification.
417
418           close_all (default for mouse_right_click)
419               Close all notifications.
420
421   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
426       close
427           command line flag: -key <key>
428
429           Specifies the keyboard shortcut for closing a notification.
430
431       close_all
432           command line flag: -all_key <key>
433
434           Specifies the keyboard shortcut for closing all currently displayed
435           notifications.
436
437       history
438           command line flag: -history_key <key>
439
440           Specifies the keyboard shortcut for recalling a single notification
441           from history.
442
443       context
444           command line flag: -context_key <key>
445
446           Specifies the keyboard shortcut that opens the context menu.
447
448   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
454       The urgency sections are urgency_low, urgency_normal, urgency_critical
455       for low, normal and critical urgency respectively.
456
457       See the example configuration file for examples.
458
459       Additionally, you can override these settings via the following command
460       line flags:
461
462       Please note these flags may be removed in the future. See issue #328 in
463       the bug tracker for discussions (See REPORTING BUGS).
464
465       -li/ni/ci icon
466           Defines the icon for low, normal and critical notifications
467           respectively.
468
469           Where icon is a path to an image file containing the icon.
470
471       -lf/nf/cf color
472           Defines the foreground color for low, normal and critical
473           notifications respectively.
474
475           See COLORS for the value format.
476
477       -lb/nb/cb color
478           Defines the background color for low, normal and critical
479           notifications respectively.
480
481           See COLORS for the value format.
482
483       -lfr/nfr/cfr color
484           Defines the frame color for low, normal and critical notifications
485           respectively.
486
487           See COLORS for more information
488
489       -lto/nto/cto secs
490           Defines the timeout time for low, normal and critical notifications
491           respectively.  See TIME FORMAT for valid times.
492

HISTORY

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
500       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

RULES

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
511       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
515       filtering
516           Notifications can be matched for any of the following attributes:
517
518           "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
522           "body"
523               The body of the notification
524
525           "category"
526               The category of the notification as defined by the notification
527               spec. See
528               https://developer.gnome.org/notification-spec/#categories
529
530           "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
535           "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
539           "match_transient"
540               Match if the notification has been declared as transient by the
541               client or by some other rule.
542
543               See "set_transient" for more details about this attribute.
544
545           "msg_urgency"
546               Matches the urgency of the notification as set by the client or
547               by some other rule.
548
549           "stack_tag"
550               Matches the stack tag of the notification as set by the client
551               or by some other rule.
552
553               See set_stack_tag for more information about stack tags.
554
555           "summary"
556               Matches the summary, 'title', of the notification.
557
558           "msg_urgency" is the urgency of the notification, it is named so to
559           not conflict with trying to modify the urgency.
560
561           Instead of the appname filter, it's recommended to use the
562           desktop_entry filter.
563
564           To define a matching rule simply assign the specified value to the
565           value that should be matched, for example:
566
567               appname="notify-send"
568
569           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
573           Shell-like globing is supported.
574
575       modifying
576           The following attributes can be overridden:
577
578           "background"
579               The background color of the notification. See COLORS for
580               possible values.
581
582           "foreground"
583               The background color of the notification. See COLORS for
584               possible values.
585
586           "format"
587               Equivalent to the "format" setting.
588
589           "frame_color"
590               The frame color color of the notification. See COLORS for
591               possible values.
592
593           "fullscreen"
594               One of show, delay, or pushback.
595
596               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
600               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
605               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
609           "new_icon"
610               Updates the icon of the notification, it should be a path to a
611               valid image.
612
613           "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
620               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
624           "set_transient"
625               Sets whether the notification is considered transient.
626               Transient notifications will bypass the idle_threshold setting.
627
628               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
632           "timeout"
633               Equivalent to the "timeout" setting in the urgency sections.
634
635           "urgency"
636               This sets the notification urgency.
637
638               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
642           "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
647           As with the filtering attributes, each one corresponds to the
648           respective notification attribute to be modified.
649
650           As with filtering, to make a rule modify an attribute simply assign
651           it in the rule definition.
652
653           If the format is set to an empty string, the notification will not
654           be suppressed.
655
656   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
661       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
665       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
668       If the notification is suppressed, the script will not be run unless
669       always_run_scripts is set to true.
670
671       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

COLORS

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
681       NOTE: '#' is interpreted as a comment, to use it the entire value needs
682       to be in quotes like so: separator_color="#123456"
683
684   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
689       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

ACTIONS

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
699       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
705       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
709       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

TIME FORMAT

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
719       Time units understood by dunst are "ms", "s", "m", "h" and "d".
720
721       Example time: "1000ms" "10m"
722

MISCELLANEOUS

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
730       killall -SIGUSR1 dunst # pause
731       killall -SIGUSR2 dunst # resume
732
733       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

FILES

740       $XDG_CONFIG_HOME/dunst/dunstrc
741
742       -or-
743
744       $HOME/.config/dunst/dunstrc
745

AUTHORS

747       Written by Sascha Kruse <knopwob@googlemail.com>
748

REPORTING BUGS

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
757       If you feel that copyrights are violated, please send me an email.
758

SEE ALSO

760       dwm(1), dmenu(1), twmn(1), notify-send(1)
761
762
763
7641.4.1                             2019-08-29                          dunst(1)
Impressum