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 start with the section's name in square brackets. After that is
11 a list of key-value pairs that specify the settings. Whitespace is
12 purely cosmetic and doesn't matter for 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: 0)
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 indicate_hidden (values: [true/false], default: true)
174 If this is set to true, a notification indicating how many
175 notifications are not being displayed due to the notification limit
176 (see notification_limit) will be shown in place of the last
177 notification slot.
178 Meaning that if this is enabled the number of visible notifications
180 will be 1 less than what is specified by notification_limit, the
181 last slot will be taken by the hidden count.
182 transparency (default: 0) (X11 only)
184 A 0-100 range on how transparent the notification window should be,
185 with 0 being fully opaque and 100 invisible.
186 To make windows transparent on wayland, set the transparency part
188 of a color, see COLORS.
189 This setting will only work if a compositor is running.
191 separator_height (default: 2)
193 The height in pixels of the separator between notifications, if set
194 to 0 there will be no separating line between notifications. This
195 setting will be ignored if gap_size is greater than 0.
196 padding (default: 8)
198 The distance in pixels from the content to the separator/border of
199 the window in the vertical axis
200 horizontal_padding (default: 8)
202 The distance in pixels from the content to the border of the window
203 in the horizontal axis
204 text_icon_padding (default: 0)
206 The distance in pixels from the text to the icon (or vice versa) in
207 the horizontal axis.
208 Setting this to a non-zero value overwrites any padding that
210 horizontal_padding was adding between the notification text and
211 icon.
212 So for example setting
214 text_icon_padding=10
216 horizontal_padding=10
217 is equivalent to
219 text_icon_padding=0
221 horizontal_padding=10
222 frame_width (default: 3)
224 Defines width in pixels of frame around the notification window.
225 Set to 0 to disable.
226 gap_size (default: 0)
228 Size of gap to display between notifications.
229 If value is greater than 0, separator_height will be ignored and a
231 border of size frame_width will be drawn around each notification
232 instead.
233 This setting requires a compositor and any applications displayed
235 between the gaps are not currently clickable.
236 separator_color (values: [auto/foreground/frame/#RRGGBB] default:
238 frame)
239 Sets the color of the separator line between two notifications.
240 auto
242 Dunst tries to find a color that fits the rest of the
243 notification color scheme automatically.
244 foreground
246 The color will be set to the same as the foreground color of
247 the topmost notification that's being separated.
248 frame
250 The color will be set to the frame color of the notification
251 with the highest urgency between the 2 notifications that are
252 being separated.
253 anything else
255 Any other value is interpreted as a color, see COLORS
256 sort (values: [true/false], default: true)
258 If set to true, display notifications with higher urgency above the
259 others.
260 idle_threshold (default: 0)
262 Don't timeout notifications if user is idle longer than this time.
263 See TIME FORMAT for valid times.
264 Set to 0 to disable.
266 A client can mark a notification as transient to bypass this
268 setting and timeout anyway. Use a rule with 'set_transient = no' to
269 disable this behavior.
270 Note: this doesn't work on xwayland.
272 layer (Wayland only)
274 One of bottom, top or overlay.
275 Place dunst notifications on the selected layer. Using overlay will
277 cause notifications to be displayed above fullscreen windows,
278 though this may also occur at top depending on your compositor.
279 The bottom layer is below all windows and above the background.
281 Default: overlay
283 force_xwayland (values: [true/false], default: false) (Wayland only)
285 Force the use of X11 output, even on a wayland compositor. This
286 setting has no effect when not using a Wayland compositor.
287 font (default: "Monospace 8")
289 Defines the font or font set used. Optionally set the size as a
290 decimal number after the font name and space. Multiple font
291 options can be separated with commas.
292 This options is parsed as a Pango font description.
294 line_height (default: 0)
296 The amount of extra spacing between text lines in pixels. Set to 0
297 to disable.
298 format (default: "<b>%s</b>\n%b")
300 Specifies how the various attributes of the notification should be
301 formatted on the notification window.
302 Regardless of the status of the markup setting, any markup tags
304 that are present in the format will be parsed. Note that because of
305 that, if a literal ampersand (&) is needed it needs to be escaped
306 as '&'
307 If '\n' is present anywhere in the format, it will be replaced with
309 a literal newline.
310 If any of the following strings are present, they will be replaced
312 with the equivalent notification attribute.
313 For a complete markup reference, see
315 <https://docs.gtk.org/Pango/pango_markup.html>.
316 %a appname
318 %s summary
319 %b body
320 %i iconname (including its path)
321 %I iconname (without its path)
322 %p progress value ([ 0%] to [100%])
323 %n progress value without any extra characters
324 %% Literal %
325 If any of these exists in the format but hasn't been specified in
327 the notification (e.g. no icon has been set), the placeholders will
328 simply be removed from the format.
329 vertical_alignment (values: [top/center/bottom], default: center)
331 Defines how the text and icon should be aligned vertically within
332 the notification. If icons are disabled, this option has no effect.
333 show_age_threshold (default: 60)
335 Show age of message if message is older than this time. See TIME
336 FORMAT for valid times.
337 Set to -1 to disable.
339 ignore_newline (values: [true/false], default: false)
341 If set to true, replace newline characters in notifications with
342 whitespace.
343 stack_duplicates (values: [true/false], default: true)
345 If set to true, duplicate notifications will be stacked together
346 instead of being displayed separately.
347 Two notifications are considered duplicate if the name of the
349 program that sent it, summary, body, icon and urgency are all
350 identical.
351 hide_duplicate_count (values: [true/false], default: false)
353 Hide the count of stacked duplicate notifications.
354 show_indicators (values: [true/false], default: true)
356 Show an indicator if a notification contains actions and/or open-
357 able URLs. See ACTIONS below for further details.
358 icon_path (default:
360 "/usr/share/icons/gnome/16x16/status/:/usr/share/icons/gnome/16x16/devices/")
361 Can be set to a colon-separated list of paths to search for icons
362 to use with notifications.
363 Dunst doens't search outside of these direcories. For a recursive
365 icon lookup system, see enable_recursive_icon_lookup. This new
366 system will eventually replace this and will need new settings.
367 icon_theme (default: "Adwaita", example: "Adwaita, breeze")
369 Comma-separated of names of the the themes to use for looking up
370 icons. This has to be the name of the directory in which the theme
371 is located, not the human-friendly name of the theme. So for
372 example, the theme Breeze Dark is located in
373 /usr/share/icons/breeze-dark. In this case you have to set the
374 theme to breeze-dark.
375 The first theme in the list is the most important. Only if the icon
377 cannot be found in that theme, the next theme will be tried.
378 Dunst will look for the themes in XDG_DATA_HOME/icons and
380 $XDG_DATA_DIRS/icons as specified in the icon theme specification:
381 https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html.
382 If the theme inherits from other themes, they will be used as a
384 backup.
385 This setting is experimental and not enabled by default. See
387 enable_recursive_icon_lookup for how to enable it.
388 enable_recursive_icon_lookup (default: false)
390 This setting enables the new icon lookup method. This new system
391 will eventually be the old icon lookup.
392 Currently icons are looked up in the icon_path. Since the icon_path
394 wasn't recursive, one had to add a ton of paths to this list. This
395 has been drastically simplified by the new lookup method. Now you
396 only have to set icon_theme to the name of the theme you want. To
397 enable this new behaviour, set enable_recursive_icon_lookup to true
398 in the [experimental] section. See the respective settings for more
399 details.
400 sticky_history (values: [true/false], default: true)
402 If set to true, notifications that have been recalled from history
403 will not time out automatically.
404 history_length (default: 20)
406 Maximum number of notifications that will be kept in history. After
407 that limit is reached, older notifications will be deleted once a
408 new one arrives. See HISTORY.
409 dmenu (default: "/usr/bin/dmenu -p dunst")
411 The command that will be run when opening the context menu. Should
412 be either a dmenu command or a dmenu-compatible menu.
413 browser (default: "/usr/bin/xdg-open")
415 The command that will be run when opening a URL. The URL to be
416 opened will be appended to the end of the value of this setting.
417 always_run_script (values: [true/false] default: true]
419 Always run rule-defined scripts, even if the notification is
420 suppressed with format = "". See SCRIPTING.
421 title (default: "Dunst")
423 Defines the title of notification windows spawned by dunst.
424 (_NET_WM_NAME property). There should be no need to modify this
425 setting for regular use.
426 class (default: "Dunst")
428 Defines the class of notification windows spawned by dunst. (First
429 part of WM_CLASS). There should be no need to modify this setting
430 for regular use.
431 force_xinerama (values: [true/false], default: false) (X11 only)
433 Use the Xinerama extension instead of RandR for multi-monitor
434 support. This setting is provided for compatibility with older
435 nVidia drivers that do not support RandR and using it on systems
436 that support RandR is highly discouraged.
437 By enabling this setting dunst will not be able to detect when a
439 monitor is connected or disconnected which might break follow mode
440 if the screen layout changes.
441 corner_radius (default: 0)
443 Define the corner radius in pixels. A corner radius of 0 will
444 result in rectangular shaped notifications.
445 By enabling this setting the outer border and the frame will be
447 shaped. If you have multiple notifications, the whole window is
448 shaped, not every single notification.
449 To avoid the corners clipping the icon or text the corner radius
451 will be automatically lowered to half of the notification height if
452 it exceeds it.
453 mouse_left/middle/right_click (values:
455 [none/do_action/close_current/close_all/context/context_all])
456 Defines action of mouse click. A touch input in Wayland acts as a
457 mouse left click.
458 none
460 Don't do anything.
461 do_action (default for mouse_middle_click)
463 Invoke the action determined by the action_name rule. If there
464 is no such action, open the context menu.
465 open_url
467 If the notification has exactly one url, open it. If there are
468 multiple ones, open the context menu.
469 close_current (default for mouse_left_click)
471 Close current notification.
472 close_all (default for mouse_right_click)
474 Close all notifications.
475 context
477 Open context menu for the notification.
478 context_all
480 Open context menu for all notifications.
481 ignore_dbusclose (default: false)
483 Ignore the dbus closeNotification message. This is useful to
484 enforce the timeout set by dunst configuration. Without this
485 parameter, an application may close the notification sent before
486 the user defined timeout.
487 Keyboard shortcuts (X11 only)
489 Keyboard shortcuts are defined in the following format: "Modifier+key"
490 where the modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any
491 keyboard key.
492 Note that the keyboard shortcuts have been moved to the global section
494 of the config for consistency with other settings.
495 Alternatively you can also define shortcuts inside your window manager
497 and bind them to dunstctl(1) commands.
498 close
500 Specifies the keyboard shortcut for closing a notification.
501 close_all
503 Specifies the keyboard shortcut for closing all currently displayed
504 notifications.
505 history
507 Specifies the keyboard shortcut for recalling a single notification
508 from history.
509 context
511 Specifies the keyboard shortcut that opens the context menu.
512 Urgency sections
514 The urgency sections work in a similar way to rules and can be used to
515 specify attributes for the different urgency levels of notifications
516 (low, normal, critical). Currently only the background, foreground,
517 hightlight, timeout, frame_color and icon attributes can be modified.
518 The urgency sections are urgency_low, urgency_normal, urgency_critical
520 for low, normal and critical urgency respectively.
521 See the example configuration file for examples.
523 The flags for setting the colors notifications of different urgencies
525 have been removed. See issue #328 in the bug tracker for discussions
526 (See REPORTING BUGS).
527 -li/ni/ci icon DEPRECATED
529 Defines the icon for low, normal and critical notifications
530 respectively. This setting will be replaced by the default_icon
531 setting, so it's recommended to replace it as soon as possible.
532 Where icon is a path to an image file containing the icon.
534 -lf/nf/cf color REMOVED
536 Defines the foreground color for low, normal and critical
537 notifications respectively.
538 See COLORS for the value format.
540 -lb/nb/cb color REMOVED
542 Defines the background color for low, normal and critical
543 notifications respectively.
544 See COLORS for the value format.
546 -lh/nh/ch color REMOVED
548 Defines the highlight color for low, normal and critical
549 notifications respectively.
550 See COLORS for the value format.
552 -lfr/nfr/cfr color REMOVED
554 Defines the frame color for low, normal and critical notifications
555 respectively.
556 See COLORS for more information
558 -lto/nto/cto secs REMOVED
560 Defines the timeout time for low, normal and critical notifications
561 respectively. See TIME FORMAT for valid times.
562
564 Dunst now contains a command line control command that can be used to
565 interact with it. It supports all functions previously done only via
566 keyboard shortcuts but also has a lot of extra functionality. For more
567 information, see dunstctl(1).
568
570 Dunst saves a number of notifications (specified by history_length) in
571 memory. These notifications can be recalled (i.e. redisplayed) by
572 calling dunstctl history (see dunstctl(1)). Whether these notifications
573 will time out like if they have been just send depends on the value of
574 the sticky_history setting. Actions are invalidated once the
575 notification is closed, so you cannot execute that action when you
576 bring back a notification from history.
577 Past notifications are redisplayed in a first-in-last-out order,
579 meaning that pressing the history key once will bring up the most
580 recent notification that had been closed/timed out.
581
583 Dunst has Wayland support since version 1.6.0. Because the Wayland
584 protocol is more focused on security, some things that are possible in
585 X11 are not possible in Wayland. Those differences are reflected in the
586 configuration. The main things that change are that dunst on Wayland
587 cannot use global hotkeys (they are deprecated anyways, use dunstctl).
588 Some dunst features on wayland might need your compositor to support a
590 certain protocol. Dunst will warn you if an optional feature isn't
591 supported and will disable the corresponding functionality.
592 Fullscreen detection works on wayland with some limitations (see
594 fullscreen). If you want notifications to appear over fullscreen
595 windows, set layer = overlay in the global options.
596 Note that the same limitations exist when using xwayland. If something
598 doesn't quite work in Wayland, please file a bug report. In the mean
599 time, you can try if the X11 output does work on wayland. Use
600 force_xwayland = true for that.
601 If you have your dunst notifications on the same side of your display
603 as your status bar, you might notice that your notifications appear a
604 bit higher or lower than on X11. This is because the notification
605 cannot be placed on top of your status bar. The notifications are
606 placed relative to your status bar, making them appear higher or lower
607 by the height of your status bar. We cannot do anything about that
608 behavior.
609
611 Rules allow the conditional modification of notifications. They can be
612 located in a section with any name, even the special sections. The
613 special sections do not allow filters to be added, since they have
614 implied filters by default.
615 'global'
617 No filters, matches all notifications.
618 'urgency_low', 'urgency_normal' and 'urgency_critical'
620 Matches low, normal or critical urgency respectively.
621 There are 2 parts in configuring a rule: Defining the filters that
623 controls when a rule should apply and then the actions that should be
624 taken when the rule is matched. It's also possible to not specify any
625 filters, in which case the rule will match all notifications.
626 Rules are applied in order of appearance. Beware: if a notification is
628 changed by a rule, it may affect if it's being matched by a later rule.
629 filtering
631 With filtering rules you can match notifications to apply rules to
632 only a subset of notifications.
633 For filtering rules that filter based on strings you can use
635 regular expressions. It's recommended to set enable_posix_regex to
636 true. You can then use the POSIX Extended Regular Expression
637 syntax:
638 https://en.m.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions.
639 Notifications can be matched for any of the following attributes.
641 "appname" (discouraged, see desktop_entry)
643 The name of the application as reported by the client. Be aware
644 that the name can often differ depending on the locale used.
645 "body"
647 The body of the notification
648 "category"
650 The category of the notification as defined by the notification
651 spec. See
652 https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html.
653 "desktop_entry"
655 GLib based applications export their desktop-entry name. In
656 comparison to the appname, the desktop-entry won't get
657 localized.
658 "icon"
660 The icon of the notification in the form of a file path. Can be
661 empty if no icon is available or a raw icon is used instead.
662 This setting is not to be confused with the icon setting in the
663 urgency section.
664 "match_transient"
666 Match if the notification has been declared as transient by the
667 client or by some other rule.
668 See "set_transient" for more details about this attribute.
670 "match_dbus_timeout"
672 Matches the dbus timeout of the notification as set by the
673 client or by some other rule.
674 See "override_dbus_timeout" for more details about this
676 attribute.
677 "msg_urgency"
679 Matches the urgency of the notification as set by the client or
680 by some other rule.
681 "stack_tag"
683 Matches the stack tag of the notification as set by the client
684 or by some other rule.
685 See set_stack_tag for more information about stack tags.
687 "summary"
689 Matches the summary, 'title', of the notification.
690 "msg_urgency" is the urgency of the notification, it is named so to
692 not conflict with trying to modify the urgency.
693 Instead of the appname filter, it's recommended to use the
695 desktop_entry filter.
696 To define a matching rule simply assign the specified value to the
698 value that should be matched, for example:
699 appname="notify-send"
701 Matches only messages that were send via notify-send. If multiple
703 filter expressions are present, all of them have to match for the
704 rule to be applied (logical AND).
705 Shell-like globing is supported.
707 modifying
709 The following attributes can be overridden:
710 "background"
712 The background color of the notification. See COLORS for
713 possible values.
714 "foreground"
716 The foreground color of the notification. See COLORS for
717 possible values.
718 "highlight"
720 The highlight color of the notification. This color is used for
721 coloring the progress bar. See COLORS for possible values.
722 "format"
724 Equivalent to the "format" setting.
725 "frame_color"
727 The frame color color of the notification. See COLORS for
728 possible values.
729 "fullscreen"
731 One of show, delay, or pushback.
732 This attribute specifies how notifications are handled if a
734 fullscreen window is focused. By default it's set to show so
735 notifications are being shown.
736 Other possible values are delay: Already shown notifications
738 are continued to be displayed until they are dismissed or time
739 out but new notifications will be held back and displayed when
740 the focus to the fullscreen window is lost.
741 Or pushback which is equivalent to delay with the difference
743 that already existing notifications are paused and hidden until
744 the focus to the fullscreen window is lost.
745 On wayland, if follow is set to mouse or keyboard, the output
747 where the notification is located cannot be determined. So
748 dunst will delay or pushback if any of the outputs is
749 fullscreen. Since the fullscreen protocol is fairly new, you
750 will need a recent version of a compositor that supports it. At
751 the time of writing, you will need the git version of sway.
752 See also layer to change if notifications appear above
753 fullscreen windows in Wayland.
754 Default: show
756 min_icon_size (default: 32)
758 Defines the minimum size in pixels for the icons. If the icon
759 is larger than or equal to the specified value it won't be
760 affected. If it's smaller then it will be scaled up so that
761 the smaller axis is equivalent to the specified size.
762 When using recursive icon lookup (see
764 enable_recursive_icon_lookup), all icons from a theme will be
765 this size.
766 If icon_position is set to off, this setting is ignored.
768 max_icon_size (default: 128)
770 Defines the maximum size in pixels for the icons. If the icon
771 is smaller than or equal to the specified value it won't be
772 affected. If it's larger then it will be scaled down so that
773 the larger axis is equivalent to the specified size.
774 Set to 0 to disable icon downscaling.
776 If both min_icon_size and max_icon_size are enabled, the latter
778 gets the last say.
779 If icon_position is set to off, this setting is ignored.
781 "new_icon"
783 Updates the icon of the notification, it should be a path or a
784 name for a valid image. This overrides the icon that was sent
785 with dunstify or another notification tool.
786 "icon_position" (values: [left/right/top/off], default: left)
788 Defines the position of the icon in the notification window.
789 Setting it to off disables icons.
790 "default_icon"
792 Sets the default icon of the notification, it should be a path
793 or a name for a valid image. This does not override the icon
794 that was sent with dunstify or another notification tool.
795 "set_stack_tag"
797 Sets the stack tag for the notification, notifications with the
798 same (non-empty) stack tag and the same appid will replace
799 each-other so only the newest one is visible. This can be
800 useful for example in volume or brightness notifications where
801 you only want one of the same type visible.
802 The stack tag can be set by the client with the 'synchronous',
804 'private-synchronous' 'x-canonical-private-synchronous' or the
805 'x-dunst-stack-tag' hints.
806 "set_transient"
808 Sets whether the notification is considered transient.
809 Transient notifications will bypass the idle_threshold setting.
810 By default notifications are _not_ considered transient but
812 clients can set the value of this by specifying the 'transient'
813 hint when sending notifications.
814 "set_category"
816 Sets the category of the notification. See
817 https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html
818 for a list of standard categories.
819 "timeout"
821 Equivalent to the "timeout" setting in the urgency sections.
822 "override_dbus_timeout"
824 Overrides the timeout specified in dbus. This takes precedence
825 over "timeout".
826 "urgency"
828 This sets the notification urgency.
829 IMPORTANT NOTE: This currently DOES NOT re-apply the attributes
831 from the urgency_* sections. The changed urgency will only be
832 visible in rules defined later. Use "msg_urgency" to match it.
833 "skip_display"
835 Setting this to true will prevent the notification from being
836 displayed initially but will be saved in history for later
837 viewing.
838 "history_ignore"
840 Setting this to true will display the notification initially,
841 but stop it from being recalled via the history.
842 "action_name"
844 Sets the name of the action to be invoked on do_action. If not
845 specified, the action set as default action or the only
846 available action will be invoked.
847 Default: "default"
849 word_wrap (values: [true/false], default: true)
851 Specifies whether to wrap the text if the lines get longer than
852 the maximum notification width. If it's set to true, long lines
853 will be broken into multiple lines expanding the notification
854 window height as necessary for them to fit. If the text doesn't
855 fit in the window, it will be ellipsize according to ellipsize.
856 ellipsize (values: [start/middle/end], default: middle)
858 Specifies where truncated lines should be ellipsized.
859 alignment (values: [left/center/right], default: left)
861 Defines how the text should be aligned within the notification.
862 hide_text (values: [true/false], default: false)
864 Setting this to true will skip displaying any text related to
865 the notification. The notification icon and progress bar will
866 still be displayed. This option may be useful for notifications
867 where an icon or progress bar may be sufficient information for
868 the notification, such as audio volume or brightness level.
869 markup (values: [full/strip/no], default: no)
871 Defines how markup in notifications is handled.
872 It's important to note that markup in the format option will be
874 parsed regardless of what this is set to.
875 Possible values:
877 full
879 Allow a small subset of html markup in notifications
880 <b>bold</b>
882 <i>italic</i>
883 <s>strikethrough</s>
884 <u>underline</u>
885 For a complete reference see
887 <https://docs.gtk.org/Pango/pango_markup.html>
888 strip
890 This setting is provided for compatibility with some broken
891 clients that send markup even though it's not enabled on
892 the server.
893 Dunst will try to strip the markup but the parsing is
895 simplistic so using this option outside of matching rules
896 for specific applications IS GREATLY DISCOURAGED.
897 See RULES
899 no Disable markup parsing, incoming notifications will be
901 treated as plain text. Dunst will not advertise that it can
902 parse markup if this is set as a global setting.
903 As with the filtering attributes, each one corresponds to the
905 respective notification attribute to be modified.
906 As with filtering, to make a rule modify an attribute simply assign
908 it in the rule definition.
909 If the format is set to an empty string, the notification will not
911 be suppressed.
912 SCRIPTING
914 Within rules you can specify a script to be run every time the rule is
915 matched by assigning the 'script' option to the name of the script to
916 be run.
917 When the script is called details of the notification that triggered it
919 will be passed via environment variables. The following variables are
920 available: DUNST_APP_NAME, DUNST_SUMMARY, DUNST_BODY, DUNST_ICON_PATH,
921 DUNST_URGENCY, DUNST_ID, DUNST_PROGRESS, DUNST_CATEGORY,
922 DUNST_STACK_TAG, DUNST_URLS, DUNST_TIMEOUT, DUNST_TIMESTAMP,
923 DUNST_DESKTOP_ENTRY, and DUNST_STACK_TAG.
924 Another, less recommended way to get notifcations details from a script
926 is via command line parameters. These are passed to the script in the
927 following order: appname, summary, body, icon_path, urgency.
928 Where DUNST_ICON_PATH or icon_path is the absolute path to the icon
930 file if there is one. DUNST_URGENCY or urgency is one of "LOW",
931 "NORMAL" or "CRITICAL". DUNST_URLS is a newline-separated list of urls
932 associated with the notification.
933 Note that some variables may be empty.
935 If the notification is suppressed, the script will not be run unless
937 always_run_scripts is set to true.
938 If '~/' occurs at the beginning of the script parameter, it will get
940 replaced by the users' home directory. If the value is not an absolute
941 path, the directories in the PATH variable will be searched for an
942 executable of the same name.
943
945 Colors are interpreted as X11 color values. This includes both verbatim
946 color names such as "Yellow", "Blue", "White", etc as well as #RGB and
947 #RRGGBB values.
948 You may also specify a transparency component in #RGBA or #RRGGBBAA
950 format.
951 NOTE: '#' is interpreted as a comment, to use it the entire value needs
953 to be in quotes like so: separator_color="#123456"
954 NOTIFY-SEND
956 dunst is able to get different colors for a message via notify-send.
957 In order to do that you have to add a hint via the -h option. The
958 progress value can be set with a hint, too.
959 All hints
961 See RULES for more detailed explanations for some options.
963 fgcolor: Foreground cololor
965 bgcolor: Background color
966 frcolor: Frame color
967 hlcolor: Highlight color
968 value: Progress value.
969 image-path: Icon name. This may be a path or just the icon name.
970 image-data: A stream of raw image data.
971 category: The category.
972 desktop-entry: The desktop entry.
973 transient: The transient value.
974 Examples
976 notify-send -h string:fgcolor:#ff4444
978 notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h
979 string:frcolor:#44ff44
980 notify-send -h int:value:42 "Working ..."
981
983 Dunst allows notifiers (i.e.: programs that send the notifications) to
984 specify actions. Dunst has support for both displaying indicators for
985 these, and interacting with these actions.
986 If "show_indicators" is true and a notification has an action, an "(A)"
988 will be prepended to the notification format. Likewise, an "(U)" is
989 prepended to notifications with URLs. It is possible to interact with
990 notifications that have actions regardless of this setting, though it
991 may not be obvious which notifications HAVE actions.
992 The "context" keybinding is used to interact with these actions, by
994 showing a menu of possible actions. This feature requires "dmenu" or a
995 dmenu drop-in replacement present.
996 Alternatively, you can invoke an action with a middle click on the
998 notification. If there is exactly one associated action, or one is
999 marked as default, that one is invoked. If there are multiple, the
1000 context menu is shown. The same applies to URLs when there are no
1001 actions.
1002
1004 A time can be any decimal integer value suffixed with a time unit. If
1005 no unit given, seconds ("s") is taken as default.
1006 Time units understood by dunst are "ms", "s", "m", "h" and "d".
1008 Example time: "1000ms" "10m"
1010
1012 Written by Sascha Kruse <knopwob@googlemail.com>
1013
1015 Bugs and suggestions should be reported on GitHub at
1016 https://github.com/dunst-project/dunst/issues
1017
1019 Copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing
1020 information)
1021 If you feel that copyrights are violated, please send me an email.
1023
1025 dunst(1), dunstctl(1), dmenu(1), notify-send(1)
10261.9.0 2022-07-21 dunst(5)