1dunst(5) Dunst Reference dunst(5)
2
6 dunst - configuration file
7
9 The configuration is divided into sections in an ini-like format. Every
10 section starts with the section's name in square brackets. After that
11 is a list of key-value pairs that specify the settings. Whitespace is
12 purely cosmetic and doesn't change the result.
13 The 'global' section contains the general settings applying to all of
15 dunst. The rest of the settings can be specified via rules and can be
16 located in any section. These rules can change a notification based on
17 it's properties. There are filtering rules and modifying rules. The
18 filtering rules specify on what notifications the rule is applied and
19 the modifying rules specify what is changed about the matching
20 notifications. Some special sections have implied filters that cannot
21 be changed. The "global" section, for example has no filters, thus
22 applies to all notifications.
23 See RULES for more details.
25 All experimental settings are marked with Experimental
27 Global section
29 monitor (default: 0)
30 Specifies on which monitor the notifications should be displayed
31 in, count starts at 0. See the follow setting.
32 follow (values: [none/mouse/keyboard] default: none)
34 Defines where the notifications should be placed in a multi-monitor
35 setup. All values except none override the monitor setting.
36 On Wayland there is no difference between mouse and keyboard focus.
38 When either of the is used, the compositor will choose an output.
39 This will generally be the output last interacted with.
40 none
42 The notifications will be placed on the monitor specified by
43 the monitor setting.
44 mouse
46 The notifications will be placed on the monitor that the mouse
47 is currently in.
48 keyboard
50 The notifications will be placed on the monitor that contains
51 the window with keyboard focus.
52 enable_posix_regex (default: false)
54 When set to true (recommended), you can use POSIX regular
55 expressions for filtering rules. It uses the POSIX Extended Regular
56 Expression syntax:
57 https://en.m.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions.
58 If this is set to false (not recommended), dunst will us fnmatch(3)
60 for matching strings. Dunst doesn't pass any flags to fnmatch, so
61 you cannot make use of extended patterns.
62 The POSIX syntax is more powerful and will eventually become the
64 default. The main differences between POSIX and fnmatch(3) is that
65 POSIX uses ".*" for wildcards instead of "*" and POSIX allows for
66 partial matches without needing wildcards. This means that the
67 pattern "abc" will match all strings that contain "abc", like
68 "abcdef".
69 geometry DEPRECATED
71 This setting is deprecated and removed. It's split up into width,
72 height, origin, notification_limit and offset. For quickly
73 transitioning to the new syntax, you can take the numbers from your
74 old geometry config as follows:
75 geometry = <width>x<height>+<offset>
76 In the new config you can then set the following variables (make
78 sure to remove any negative signs)
79 width = <width>
80 height = <height>
81 offset = <offset>
82 origin = top-right # or top-left, or any other direction
83 you prefer
84 width
86 The width of the notification window in pixels. This can be a
87 single number to specify a constant width or two numbers for the
88 minimum and maximum width. The notification will expand from the
89 minimum width as neccesary.
90 Examples:
92 width = 300 # constant width of 300
93 width = (0, 300) # width between 0 and 300
94 When setting a width bigger than the screen, dunst will clamp the
96 width to the screen width. So if you want the notifcation to
97 stretch the entire screen dynamically, you may set the width to a
98 high enough number, which none of your screens exceed (e.g. 10000).
99 height
101 The maximum height of a single notification.
102 notification_limit (default: 20)
104 The number of notifications that can appear at one time. When this
105 limit is reached any additional notifications will be queued and
106 displayed when the currently displayed ones either time out or are
107 manually dismissed. The value 0 means no limit. If indicate_hidden
108 is true, then the specified limit is reduced by 1 and the last
109 notification is a message informing how many hidden notifications
110 are waiting to be displayed. See the indicate_hidden entry for more
111 information.
112 origin (default: top-right)
114 The origin of the notification window on the screen. It can then be
115 moved with offset. Origin can be one of:
116 top-left
117 top-center
118 top-right
119 bottom-left
120 bottom-center
121 bottom-right
122 left-center
123 center
124 right-center
125 offset format: (horizontal, vertical)
127 Respectively the horizontal and vertical offset in pixels from the
128 corner of the screen specified by origin. A negative offset will
129 lead to the notification being off screen.
130 Examples:
132 origin = top-right
133 offset = 10x300 # a margin of 10 pixels from the right and
134 300 pixels from the top
135 scale (default: 0, X11 only)
137 Specifies a scale factor for dimensions to adapt notifications to
138 HiDPI screens. This scales the notification geometry and it's
139 contents. It is not recommended to use a fractional scaling factor,
140 as this may result in things being one pixel off. Try to use a
141 whole number scaling factor and adjust the font size and other
142 sizes as needed. If 0 is specified, the scale factor is auto-
143 detected.
144 progress_bar (values: [true/false], default: true)
146 When an integer value is passed to dunst as a hint (see NOTIFY-
147 SEND), a progress bar will be drawn at the bottom of the
148 notification. This behavior can be turned off by setting this
149 setting to false.
150 progress_bar_horizontal_alignment (values: [left/center/right],
152 default: center)
153 Horizontal alignment of the progress bar. The progress bar will
154 always keep a distance of horizontal_padding from the edge of the
155 notification.
156 progress_bar_height (default: 10)
158 The height of the progress bar in pixel. This includes the frame.
159 Make sure this value is bigger than twice the frame width.
160 progress_bar_min_width (default: 150)
162 The minimum width of the progress bar in pixels. The notification
163 is rescaled to fit the bar.
164 progress_bar_max_width (default: 300)
166 The maximum width of the progress bar in pixels. The notification
167 is resized to fit the progress bar.
168 progress_bar_frame_width (default: 1)
170 The frame width of the progress bar in pixels. This value should be
171 smaller than half of the progress bar height.
172 progress_bar_corner_radius (default: 0)
174 The corner radius of the progress bar in pixels. Gives the progress
175 bar rounded corners. Set to 0 to disable.
176 icon_corner_radius (default: 0)
178 The corner radius of the icon image in pixels. Gives the icon
179 rounded corners. Set to 0 to disable.
180 indicate_hidden (values: [true/false], default: true)
182 If this is set to true, a notification indicating how many
183 notifications are not being displayed due to the notification limit
184 (see notification_limit) will be shown in place of the last
185 notification slot.
186 Meaning that if this is enabled the number of visible notifications
188 will be 1 less than what is specified by notification_limit, the
189 last slot will be taken by the hidden count.
190 transparency (default: 0) (X11 only)
192 A 0-100 range on how transparent the notification window should be,
193 with 0 being fully opaque and 100 invisible.
194 To make windows transparent on wayland, set the transparency part
196 of a color, see COLORS.
197 This setting will only work if a compositor is running.
199 separator_height (default: 2)
201 The height in pixels of the separator between notifications, if set
202 to 0 there will be no separating line between notifications. This
203 setting will be ignored if gap_size is greater than 0.
204 padding (default: 8)
206 The distance in pixels from the content to the separator/border of
207 the window in the vertical axis
208 horizontal_padding (default: 8)
210 The distance in pixels from the content to the border of the window
211 in the horizontal axis
212 text_icon_padding (default: 0)
214 The distance in pixels from the text to the icon (or vice versa) in
215 the horizontal axis.
216 Setting this to a non-zero value overwrites any padding that
218 horizontal_padding was adding between the notification text and
219 icon.
220 So for example setting
222 text_icon_padding=10
224 horizontal_padding=10
225 is equivalent to
227 text_icon_padding=0
229 horizontal_padding=10
230 frame_width (default: 3)
232 Defines width in pixels of frame around the notification window.
233 Set to 0 to disable.
234 gap_size (default: 0)
236 Size of gap to display between notifications.
237 If value is greater than 0, separator_height will be ignored and a
239 border of size frame_width will be drawn around each notification
240 instead.
241 This setting requires a compositor and any applications displayed
243 between the gaps are not currently clickable.
244 separator_color (values: [auto/foreground/frame/#RRGGBB] default:
246 frame)
247 Sets the color of the separator line between two notifications.
248 auto
250 Dunst tries to find a color that fits the rest of the
251 notification color scheme automatically.
252 foreground
254 The color will be set to the same as the foreground color of
255 the topmost notification that's being separated.
256 frame
258 The color will be set to the frame color of the notification
259 with the highest urgency between the 2 notifications that are
260 being separated.
261 anything else
263 Any other value is interpreted as a color, see COLORS
264 sort (values: [true/false], default: true)
266 If set to true, display notifications with higher urgency above the
267 others.
268 idle_threshold (default: 0)
270 Don't timeout notifications if user is idle longer than this time.
271 See TIME FORMAT for valid times.
272 Set to 0 to disable.
274 A client can mark a notification as transient to bypass this
276 setting and timeout anyway. Use a rule with 'set_transient = no' to
277 disable this behavior.
278 Note: this doesn't work on xwayland.
280 layer (Wayland only)
282 One of bottom, top or overlay.
283 Place dunst notifications on the selected layer. Using overlay will
285 cause notifications to be displayed above fullscreen windows,
286 though this may also occur at top depending on your compositor.
287 The bottom layer is below all windows and above the background.
289 Default: overlay
291 force_xwayland (values: [true/false], default: false) (Wayland only)
293 Force the use of X11 output, even on a wayland compositor. This
294 setting has no effect when not using a Wayland compositor.
295 font (default: "Monospace 8")
297 Defines the font or font set used. Optionally set the size as a
298 decimal number after the font name and space. Multiple font
299 options can be separated with commas.
300 This options is parsed as a Pango font description.
302 line_height (default: 0)
304 The amount of extra spacing between text lines in pixels. Set to 0
305 to disable.
306 format (default: "<b>%s</b>\n%b")
308 Specifies how the various attributes of the notification should be
309 formatted on the notification window.
310 Regardless of the status of the markup setting, any markup tags
312 that are present in the format will be parsed. Note that because of
313 that, if a literal ampersand (&) is needed it needs to be escaped
314 as '&'
315 If '\n' is present anywhere in the format, it will be replaced with
317 a literal newline.
318 If any of the following strings are present, they will be replaced
320 with the equivalent notification attribute.
321 For a complete markup reference, see
323 <https://docs.gtk.org/Pango/pango_markup.html>.
324 %a appname
326 %s summary
327 %b body
328 %i iconname (including its path)
329 %I iconname (without its path)
330 %p progress value ([ 0%] to [100%])
331 %n progress value without any extra characters
332 %% Literal %
333 If any of these exists in the format but hasn't been specified in
335 the notification (e.g. no icon has been set), the placeholders will
336 simply be removed from the format.
337 vertical_alignment (values: [top/center/bottom], default: center)
339 Defines how the text and icon should be aligned vertically within
340 the notification. If icons are disabled, this option has no effect.
341 show_age_threshold (default: 60)
343 Show age of message if message is older than this time. See TIME
344 FORMAT for valid times.
345 Set to -1 to disable.
347 ignore_newline (values: [true/false], default: false)
349 If set to true, replace newline characters in notifications with
350 whitespace.
351 stack_duplicates (values: [true/false], default: true)
353 If set to true, duplicate notifications will be stacked together
354 instead of being displayed separately.
355 Two notifications are considered duplicate if the name of the
357 program that sent it, summary, body, icon and urgency are all
358 identical.
359 hide_duplicate_count (values: [true/false], default: false)
361 Hide the count of stacked duplicate notifications.
362 show_indicators (values: [true/false], default: true)
364 Show an indicator if a notification contains actions and/or open-
365 able URLs. See ACTIONS below for further details.
366 icon_path (default:
368 "/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/")
369 Can be set to a colon-separated list of paths to search for icons
370 to use with notifications.
371 Dunst doens't search outside of these direcories. For a recursive
373 icon lookup system, see enable_recursive_icon_lookup. This new
374 system will eventually replace this and will need new settings.
375 icon_theme (default: "Adwaita", example: "Adwaita, breeze")
377 Comma-separated of names of the the themes to use for looking up
378 icons. This has to be the name of the directory in which the theme
379 is located, not the human-friendly name of the theme. So for
380 example, the theme Breeze Dark is located in
381 /usr/share/icons/breeze-dark. In this case you have to set the
382 theme to breeze-dark.
383 The first theme in the list is the most important. Only if the icon
385 cannot be found in that theme, the next theme will be tried.
386 Dunst will look for the themes in XDG_DATA_HOME/icons and
388 $XDG_DATA_DIRS/icons as specified in the icon theme specification:
389 https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html.
390 If the theme inherits from other themes, they will be used as a
392 backup.
393 This setting is experimental and not enabled by default. See
395 enable_recursive_icon_lookup for how to enable it.
396 enable_recursive_icon_lookup (default: false)
398 This setting enables the new icon lookup method. This new system
399 will eventually be the old icon lookup.
400 Currently icons are looked up in the icon_path. Since the icon_path
402 wasn't recursive, one had to add a ton of paths to this list. This
403 has been drastically simplified by the new lookup method. Now you
404 only have to set icon_theme to the name of the theme you want. To
405 enable this new behaviour, set enable_recursive_icon_lookup to true
406 in the [experimental] section. See the respective settings for more
407 details.
408 sticky_history (values: [true/false], default: true)
410 If set to true, notifications that have been recalled from history
411 will not time out automatically.
412 history_length (default: 20)
414 Maximum number of notifications that will be kept in history. After
415 that limit is reached, older notifications will be deleted once a
416 new one arrives. See HISTORY.
417 dmenu (default: "/usr/bin/dmenu -p dunst")
419 The command that will be run when opening the context menu. Should
420 be either a dmenu command or a dmenu-compatible menu.
421 browser (default: "/usr/bin/xdg-open")
423 The command that will be run when opening a URL. The URL to be
424 opened will be appended to the end of the value of this setting.
425 always_run_script (values: [true/false] default: true]
427 Always run rule-defined scripts, even if the notification is
428 suppressed with format = "". See SCRIPTING.
429 title (default: "Dunst")
431 Defines the title of notification windows spawned by dunst.
432 (_NET_WM_NAME property). There should be no need to modify this
433 setting for regular use.
434 class (default: "Dunst")
436 Defines the class of notification windows spawned by dunst. (First
437 part of WM_CLASS). There should be no need to modify this setting
438 for regular use.
439 force_xinerama (values: [true/false], default: false) (X11 only)
441 Use the Xinerama extension instead of RandR for multi-monitor
442 support. This setting is provided for compatibility with older
443 nVidia drivers that do not support RandR and using it on systems
444 that support RandR is highly discouraged.
445 By enabling this setting dunst will not be able to detect when a
447 monitor is connected or disconnected which might break follow mode
448 if the screen layout changes.
449 corner_radius (default: 0)
451 Define the corner radius in pixels. A corner radius of 0 will
452 result in rectangular shaped notifications.
453 By enabling this setting the outer border and the frame will be
455 shaped. If you have multiple notifications, the whole window is
456 shaped, not every single notification.
457 To avoid the corners clipping the icon or text the corner radius
459 will be automatically lowered to half of the notification height if
460 it exceeds it.
461 mouse_left/middle/right_click (values:
463 [none/do_action/close_current/close_all/context/context_all])
464 Defines action of mouse click. A touch input in Wayland acts as a
465 mouse left click.
466 none
468 Don't do anything.
469 do_action (default for mouse_middle_click)
471 Invoke the action determined by the action_name rule. If there
472 is no such action, open the context menu.
473 open_url
475 If the notification has exactly one url, open it. If there are
476 multiple ones, open the context menu.
477 close_current (default for mouse_left_click)
479 Close current notification.
480 close_all (default for mouse_right_click)
482 Close all notifications.
483 context
485 Open context menu for the notification.
486 context_all
488 Open context menu for all notifications.
489 ignore_dbusclose (default: false)
491 Ignore the dbus closeNotification message. This is useful to
492 enforce the timeout set by dunst configuration. Without this
493 parameter, an application may close the notification sent before
494 the user defined timeout.
495 Keyboard shortcuts (X11 only)
497 Keyboard shortcuts are defined in the following format: "Modifier+key"
498 where the modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any
499 keyboard key.
500 Note that the keyboard shortcuts have been moved to the global section
502 of the config for consistency with other settings.
503 Alternatively you can also define shortcuts inside your window manager
505 and bind them to dunstctl(1) commands.
506 close
508 Specifies the keyboard shortcut for closing a notification.
509 close_all
511 Specifies the keyboard shortcut for closing all currently displayed
512 notifications.
513 history
515 Specifies the keyboard shortcut for recalling a single notification
516 from history.
517 context
519 Specifies the keyboard shortcut that opens the context menu.
520 Urgency sections
522 The urgency sections work in a similar way to rules and can be used to
523 specify attributes for the different urgency levels of notifications
524 (low, normal, critical). Currently only the background, foreground,
525 hightlight, timeout, frame_color and icon attributes can be modified.
526 The urgency sections are urgency_low, urgency_normal, urgency_critical
528 for low, normal and critical urgency respectively.
529 See the example configuration file for examples.
531 The flags for setting the colors notifications of different urgencies
533 have been removed. See issue #328 in the bug tracker for discussions
534 (See REPORTING BUGS).
535 -li/ni/ci icon DEPRECATED
537 Defines the icon for low, normal and critical notifications
538 respectively. This setting will be replaced by the default_icon
539 setting, so it's recommended to replace it as soon as possible.
540 Where icon is a path to an image file containing the icon.
542 -lf/nf/cf color REMOVED
544 Defines the foreground color for low, normal and critical
545 notifications respectively.
546 See COLORS for the value format.
548 -lb/nb/cb color REMOVED
550 Defines the background color for low, normal and critical
551 notifications respectively.
552 See COLORS for the value format.
554 -lh/nh/ch color REMOVED
556 Defines the highlight color for low, normal and critical
557 notifications respectively.
558 See COLORS for the value format.
560 -lfr/nfr/cfr color REMOVED
562 Defines the frame color for low, normal and critical notifications
563 respectively.
564 See COLORS for more information
566 -lto/nto/cto secs REMOVED
568 Defines the timeout time for low, normal and critical notifications
569 respectively. See TIME FORMAT for valid times.
570
572 Dunst now contains a command line control command that can be used to
573 interact with it. It supports all functions previously done only via
574 keyboard shortcuts but also has a lot of extra functionality. For more
575 information, see dunstctl(1).
576
578 Dunst saves a number of notifications (specified by history_length) in
579 memory. These notifications can be recalled (i.e. redisplayed) by
580 calling dunstctl history (see dunstctl(1)). Whether these notifications
581 will time out like if they have been just send depends on the value of
582 the sticky_history setting. Actions are invalidated once the
583 notification is closed, so you cannot execute that action when you
584 bring back a notification from history.
585 Past notifications are redisplayed in a first-in-last-out order,
587 meaning that pressing the history key once will bring up the most
588 recent notification that had been closed/timed out.
589
591 Dunst has Wayland support since version 1.6.0. Because the Wayland
592 protocol is more focused on security, some things that are possible in
593 X11 are not possible in Wayland. Those differences are reflected in the
594 configuration. The main things that change are that dunst on Wayland
595 cannot use global hotkeys (they are deprecated anyways, use dunstctl).
596 Some dunst features on wayland might need your compositor to support a
598 certain protocol. Dunst will warn you if an optional feature isn't
599 supported and will disable the corresponding functionality.
600 Fullscreen detection works on wayland with some limitations (see
602 fullscreen). If you want notifications to appear over fullscreen
603 windows, set layer = overlay in the global options.
604 Note that the same limitations exist when using xwayland. If something
606 doesn't quite work in Wayland, please file a bug report. In the mean
607 time, you can try if the X11 output does work on wayland. Use
608 force_xwayland = true for that.
609 If you have your dunst notifications on the same side of your display
611 as your status bar, you might notice that your notifications appear a
612 bit higher or lower than on X11. This is because the notification
613 cannot be placed on top of your status bar. The notifications are
614 placed relative to your status bar, making them appear higher or lower
615 by the height of your status bar. We cannot do anything about that
616 behavior.
617
619 Rules allow the conditional modification of notifications. They can be
620 located in a section with any name, even the special sections. The
621 special sections do not allow filters to be added, since they have
622 implied filters by default.
623 'global'
625 No filters, matches all notifications.
626 'urgency_low', 'urgency_normal' and 'urgency_critical'
628 Matches low, normal or critical urgency respectively.
629 There are 2 parts in configuring a rule: Defining the filters that
631 controls when a rule should apply and then the actions that should be
632 taken when the rule is matched. It's also possible to not specify any
633 filters, in which case the rule will match all notifications.
634 Rules are applied in order of appearance. Beware: if a notification is
636 changed by a rule, it may affect if it's being matched by a later rule.
637 filtering
639 With filtering rules you can match notifications to apply rules to
640 only a subset of notifications.
641 For filtering rules that filter based on strings you can use
643 regular expressions. It's recommended to set enable_posix_regex to
644 true. You can then use the POSIX Extended Regular Expression
645 syntax:
646 https://en.m.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions.
647 Notifications can be matched for any of the following attributes.
649 "appname" (discouraged, see desktop_entry)
651 The name of the application as reported by the client. Be aware
652 that the name can often differ depending on the locale used.
653 "body"
655 The body of the notification
656 "category"
658 The category of the notification as defined by the notification
659 spec. See
660 https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html.
661 "desktop_entry"
663 GLib based applications export their desktop-entry name. In
664 comparison to the appname, the desktop-entry won't get
665 localized.
666 "icon"
668 The icon of the notification in the form of a file path. Can be
669 empty if no icon is available or a raw icon is used instead.
670 This setting is not to be confused with the icon setting in the
671 urgency section.
672 "match_transient"
674 Match if the notification has been declared as transient by the
675 client or by some other rule.
676 See "set_transient" for more details about this attribute.
678 "match_dbus_timeout"
680 Matches the dbus timeout of the notification as set by the
681 client or by some other rule.
682 See "override_dbus_timeout" for more details about this
684 attribute.
685 "msg_urgency"
687 Matches the urgency of the notification as set by the client or
688 by some other rule.
689 "stack_tag"
691 Matches the stack tag of the notification as set by the client
692 or by some other rule.
693 See set_stack_tag for more information about stack tags.
695 "summary"
697 Matches the summary, 'title', of the notification.
698 "msg_urgency" is the urgency of the notification, it is named so to
700 not conflict with trying to modify the urgency.
701 Instead of the appname filter, it's recommended to use the
703 desktop_entry filter.
704 To define a matching rule simply assign the specified value to the
706 value that should be matched, for example:
707 appname="notify-send"
709 Matches only messages that were send via notify-send. If multiple
711 filter expressions are present, all of them have to match for the
712 rule to be applied (logical AND).
713 Shell-like globing is supported.
715 modifying
717 The following attributes can be overridden:
718 "background"
720 The background color of the notification. See COLORS for
721 possible values.
722 "foreground"
724 The foreground color of the notification. See COLORS for
725 possible values.
726 "highlight"
728 The highlight color of the notification. This color is used for
729 coloring the progress bar. See COLORS for possible values.
730 "format"
732 Equivalent to the "format" setting.
733 "frame_color"
735 The frame color color of the notification. See COLORS for
736 possible values.
737 "fullscreen"
739 One of show, delay, or pushback.
740 This attribute specifies how notifications are handled if a
742 fullscreen window is focused. By default it's set to show so
743 notifications are being shown.
744 Other possible values are delay: Already shown notifications
746 are continued to be displayed until they are dismissed or time
747 out but new notifications will be held back and displayed when
748 the focus to the fullscreen window is lost.
749 Or pushback which is equivalent to delay with the difference
751 that already existing notifications are paused and hidden until
752 the focus to the fullscreen window is lost.
753 On wayland, if follow is set to mouse or keyboard, the output
755 where the notification is located cannot be determined. So
756 dunst will delay or pushback if any of the outputs is
757 fullscreen. Since the fullscreen protocol is fairly new, you
758 will need a recent version of a compositor that supports it. At
759 the time of writing, you will need the git version of sway.
760 See also layer to change if notifications appear above
761 fullscreen windows in Wayland.
762 Default: show
764 min_icon_size (default: 32)
766 Defines the minimum size in pixels for the icons. If the icon
767 is larger than or equal to the specified value it won't be
768 affected. If it's smaller then it will be scaled up so that
769 the smaller axis is equivalent to the specified size.
770 When using recursive icon lookup (see
772 enable_recursive_icon_lookup), all icons from a theme will be
773 this size.
774 If icon_position is set to off, this setting is ignored.
776 max_icon_size (default: 128)
778 Defines the maximum size in pixels for the icons. If the icon
779 is smaller than or equal to the specified value it won't be
780 affected. If it's larger then it will be scaled down so that
781 the larger axis is equivalent to the specified size.
782 Set to 0 to disable icon downscaling.
784 If both min_icon_size and max_icon_size are enabled, the latter
786 gets the last say.
787 If icon_position is set to off, this setting is ignored.
789 "new_icon"
791 Updates the icon of the notification, it should be a path or a
792 name for a valid image. This overrides the icon that was sent
793 with dunstify or another notification tool.
794 "icon_position" (values: [left/right/top/off], default: left)
796 Defines the position of the icon in the notification window.
797 Setting it to off disables icons.
798 "default_icon"
800 Sets the default icon of the notification, it should be a path
801 or a name for a valid image. This does not override the icon
802 that was sent with dunstify or another notification tool.
803 "set_stack_tag"
805 Sets the stack tag for the notification, notifications with the
806 same (non-empty) stack tag and the same appid will replace
807 each-other so only the newest one is visible. This can be
808 useful for example in volume or brightness notifications where
809 you only want one of the same type visible.
810 The stack tag can be set by the client with the 'synchronous',
812 'private-synchronous' 'x-canonical-private-synchronous' or the
813 'x-dunst-stack-tag' hints.
814 "set_transient"
816 Sets whether the notification is considered transient.
817 Transient notifications will bypass the idle_threshold setting.
818 By default notifications are _not_ considered transient but
820 clients can set the value of this by specifying the 'transient'
821 hint when sending notifications.
822 "set_category"
824 Sets the category of the notification. See
825 https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html
826 for a list of standard categories.
827 "timeout"
829 Equivalent to the "timeout" setting in the urgency sections.
830 "override_dbus_timeout"
832 Overrides the timeout specified in dbus. This takes precedence
833 over "timeout".
834 "urgency"
836 This sets the notification urgency.
837 IMPORTANT NOTE: This currently DOES NOT re-apply the attributes
839 from the urgency_* sections. The changed urgency will only be
840 visible in rules defined later. Use "msg_urgency" to match it.
841 "skip_display"
843 Setting this to true will prevent the notification from being
844 displayed initially but will be saved in history for later
845 viewing.
846 "history_ignore"
848 Setting this to true will display the notification initially,
849 but stop it from being recalled via the history.
850 "action_name"
852 Sets the name of the action to be invoked on do_action. If not
853 specified, the action set as default action or the only
854 available action will be invoked.
855 Default: "default"
857 word_wrap (values: [true/false], default: true)
859 Specifies whether to wrap the text if the lines get longer than
860 the maximum notification width. If it's set to true, long lines
861 will be broken into multiple lines expanding the notification
862 window height as necessary for them to fit. If the text doesn't
863 fit in the window, it will be ellipsize according to ellipsize.
864 ellipsize (values: [start/middle/end], default: middle)
866 Specifies where truncated lines should be ellipsized.
867 alignment (values: [left/center/right], default: left)
869 Defines how the text should be aligned within the notification.
870 hide_text (values: [true/false], default: false)
872 Setting this to true will skip displaying any text related to
873 the notification. The notification icon and progress bar will
874 still be displayed. This option may be useful for notifications
875 where an icon or progress bar may be sufficient information for
876 the notification, such as audio volume or brightness level.
877 markup (values: [full/strip/no], default: no)
879 Defines how markup in notifications is handled.
880 It's important to note that markup in the format option will be
882 parsed regardless of what this is set to.
883 Possible values:
885 full
887 Allow a small subset of html markup in notifications
888 <b>bold</b>
890 <i>italic</i>
891 <s>strikethrough</s>
892 <u>underline</u>
893 For a complete reference see
895 <https://docs.gtk.org/Pango/pango_markup.html>
896 strip
898 This setting is provided for compatibility with some broken
899 clients that send markup even though it's not enabled on
900 the server.
901 Dunst will try to strip the markup but the parsing is
903 simplistic so using this option outside of matching rules
904 for specific applications IS GREATLY DISCOURAGED.
905 See RULES
907 no Disable markup parsing, incoming notifications will be
909 treated as plain text. Dunst will not advertise that it can
910 parse markup if this is set as a global setting.
911 As with the filtering attributes, each one corresponds to the
913 respective notification attribute to be modified.
914 As with filtering, to make a rule modify an attribute simply assign
916 it in the rule definition.
917 If the format is set to an empty string, the notification will not
919 be suppressed.
920 SCRIPTING
922 Within rules you can specify a script to be run every time the rule is
923 matched by assigning the 'script' option to the name of the script to
924 be run.
925 When the script is called details of the notification that triggered it
927 will be passed via environment variables. The following variables are
928 available: DUNST_APP_NAME, DUNST_SUMMARY, DUNST_BODY, DUNST_ICON_PATH,
929 DUNST_URGENCY, DUNST_ID, DUNST_PROGRESS, DUNST_CATEGORY,
930 DUNST_STACK_TAG, DUNST_URLS, DUNST_TIMEOUT, DUNST_TIMESTAMP,
931 DUNST_DESKTOP_ENTRY, and DUNST_STACK_TAG.
932 Another, less recommended way to get notifcations details from a script
934 is via command line parameters. These are passed to the script in the
935 following order: appname, summary, body, icon_path, urgency.
936 Where DUNST_ICON_PATH or icon_path is the absolute path to the icon
938 file if there is one. DUNST_URGENCY or urgency is one of "LOW",
939 "NORMAL" or "CRITICAL". DUNST_URLS is a newline-separated list of urls
940 associated with the notification.
941 Note that some variables may be empty.
943 If the notification is suppressed, the script will not be run unless
945 always_run_scripts is set to true.
946 If '~/' occurs at the beginning of the script parameter, it will get
948 replaced by the users' home directory. If the value is not an absolute
949 path, the directories in the PATH variable will be searched for an
950 executable of the same name.
951
953 Colors are interpreted as X11 color values. This includes both verbatim
954 color names such as "Yellow", "Blue", "White", etc as well as #RGB and
955 #RRGGBB values.
956 You may also specify a transparency component in #RGBA or #RRGGBBAA
958 format.
959 NOTE: '#' is interpreted as a comment, to use it the entire value needs
961 to be in quotes like so: separator_color="#123456"
962 NOTIFY-SEND
964 dunst is able to get different colors for a message via notify-send.
965 In order to do that you have to add a hint via the -h option. The
966 progress value can be set with a hint, too.
967 All hints
969 See RULES for more detailed explanations for some options.
971 fgcolor: Foreground cololor
973 bgcolor: Background color
974 frcolor: Frame color
975 hlcolor: Highlight color
976 value: Progress value.
977 image-path: Icon name. This may be a path or just the icon name.
978 image-data: A stream of raw image data.
979 category: The category.
980 desktop-entry: The desktop entry.
981 transient: The transient value.
982 Examples
984 notify-send -h string:fgcolor:#ff4444
986 notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h
987 string:frcolor:#44ff44
988 notify-send -h int:value:42 "Working ..."
989
991 Dunst allows notifiers (i.e.: programs that send the notifications) to
992 specify actions. Dunst has support for both displaying indicators for
993 these, and interacting with these actions.
994 If "show_indicators" is true and a notification has an action, an "(A)"
996 will be prepended to the notification format. Likewise, an "(U)" is
997 prepended to notifications with URLs. It is possible to interact with
998 notifications that have actions regardless of this setting, though it
999 may not be obvious which notifications HAVE actions.
1000 The "context" keybinding is used to interact with these actions, by
1002 showing a menu of possible actions. This feature requires "dmenu" or a
1003 dmenu drop-in replacement present.
1004 Alternatively, you can invoke an action with a middle click on the
1006 notification. If there is exactly one associated action, or one is
1007 marked as default, that one is invoked. If there are multiple, the
1008 context menu is shown. The same applies to URLs when there are no
1009 actions.
1010
1012 A time can be any decimal integer value suffixed with a time unit. If
1013 no unit given, seconds ("s") is taken as default.
1014 Time units understood by dunst are "ms", "s", "m", "h" and "d".
1016 Example time: "1000ms" "10m"
1018
1020 Written by Sascha Kruse <knopwob@googlemail.com>
1021
1023 Bugs and suggestions should be reported on GitHub at
1024 https://github.com/dunst-project/dunst/issues
1025
1027 Copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing
1028 information)
1029 If you feel that copyrights are violated, please send me an email.
1031
1033 dunst(1), dunstctl(1), dmenu(1), notify-send(1)
10341.9.2 2023-07-19 dunst(5)