| dunst(5) | Dunst Reference | dunst(5) |
dunst - configuration file
The configuration is divided into sections in an ini-like format. Every section start with the section's name in square brackets. After that is a list of key-value pairs that specify the settings. Whitespace is purely cosmetic and doesn't matter for the result.
The 'global' section contains the general settings applying to all of dunst. The rest of the settings can be specified via rules and can be located in any section. These rules can change a notification based on it's properties. There are filtering rules and modifying rules. The filtering rules specify on what notifications the rule is applied and the modifying rules specify what is changed about the matching notifications. Some special sections have implied filters that cannot be changed. The "global" section, for example has no filters, thus applies to all notifications.
See RULES for more details.
All experimental settings are marked with Experimental
On Wayland there is no difference between mouse and keyboard focus. When either of the is used, the compositor will choose an output. This will generally be the output last interacted with.
If this is set to false (not recommended), dunst will us fnmatch(3) for matching strings. Dunst doesn't pass any flags to fnmatch, so you cannot make use of extended patterns.
The POSIX syntax is more powerful and will eventually become the default. The main differences between POSIX and fnmatch(3) is that POSIX uses ".*" for wildcards instead of "*" and POSIX allows for partial matches without needing wildcards. This means that the pattern "abc" will match all strings that contain "abc", like "abcdef".
In the new config you can then set the following variables
(make sure to remove any negative signs)
width = <width>
height = <height>
offset = <offset>
origin = top-right # or top-left, or any other direction you prefer
Examples:
width = 300 # constant width of 300
width = (0, 300) # width between 0 and 300
When setting a width bigger than the screen, dunst will clamp the width to the screen width. So if you want the notifcation to stretch the entire screen dynamically, you may set the width to a high enough number, which none of your screens exceed (e.g. 10000).
Examples:
origin = top-right
offset = 10x300 # a margin of 10 pixels from the right and 300 pixels
from the top
Meaning that if this is enabled the number of visible notifications will be 1 less than what is specified by notification_limit, the last slot will be taken by the hidden count.
To make windows transparent on wayland, set the transparency part of a color, see COLORS.
This setting will only work if a compositor is running.
Setting this to a non-zero value overwrites any padding that horizontal_padding was adding between the notification text and icon.
So for example setting
text_icon_padding=10
horizontal_padding=10
is equivalent to
text_icon_padding=0
horizontal_padding=10
If value is greater than 0, separator_height will be ignored and a border of size frame_width will be drawn around each notification instead.
This setting requires a compositor and any applications displayed between the gaps are not currently clickable.
Set to 0 to disable.
A client can mark a notification as transient to bypass this setting and timeout anyway. Use a rule with 'set_transient = no' to disable this behavior.
Note: this doesn't work on xwayland.
Place dunst notifications on the selected layer. Using overlay will cause notifications to be displayed above fullscreen windows, though this may also occur at top depending on your compositor.
The bottom layer is below all windows and above the background.
Default: overlay
This options is parsed as a Pango font description.
Regardless of the status of the markup setting, any markup tags that are present in the format will be parsed. Note that because of that, if a literal ampersand (&) is needed it needs to be escaped as '&'
If '\n' is present anywhere in the format, it will be replaced with a literal newline.
If any of the following strings are present, they will be replaced with the equivalent notification attribute.
For a complete markup reference, see <https://docs.gtk.org/Pango/pango_markup.html>.
If any of these exists in the format but hasn't been specified in the notification (e.g. no icon has been set), the placeholders will simply be removed from the format.
Set to -1 to disable.
Two notifications are considered duplicate if the name of the program that sent it, summary, body, icon and urgency are all identical.
Dunst doens't search outside of these direcories. For a recursive icon lookup system, see enable_recursive_icon_lookup. This new system will eventually replace this and will need new settings.
The first theme in the list is the most important. Only if the icon cannot be found in that theme, the next theme will be tried.
Dunst will look for the themes in XDG_DATA_HOME/icons and $XDG_DATA_DIRS/icons as specified in the icon theme specification: https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html.
If the theme inherits from other themes, they will be used as a backup.
This setting is experimental and not enabled by default. See enable_recursive_icon_lookup for how to enable it.
Currently icons are looked up in the icon_path. Since the icon_path wasn't recursive, one had to add a ton of paths to this list. This has been drastically simplified by the new lookup method. Now you only have to set icon_theme to the name of the theme you want. To enable this new behaviour, set enable_recursive_icon_lookup to true in the [experimental] section. See the respective settings for more details.
By enabling this setting dunst will not be able to detect when a monitor is connected or disconnected which might break follow mode if the screen layout changes.
By enabling this setting the outer border and the frame will be shaped. If you have multiple notifications, the whole window is shaped, not every single notification.
To avoid the corners clipping the icon or text the corner radius will be automatically lowered to half of the notification height if it exceeds it.
Keyboard shortcuts are defined in the following format: "Modifier+key" where the modifier is one of ctrl,mod1,mod2,mod3,mod4 and key is any keyboard key.
Note that the keyboard shortcuts have been moved to the global section of the config for consistency with other settings.
Alternatively you can also define shortcuts inside your window manager and bind them to dunstctl(1) commands.
The urgency sections work in a similar way to rules and can be used to specify attributes for the different urgency levels of notifications (low, normal, critical). Currently only the background, foreground, hightlight, timeout, frame_color and icon attributes can be modified.
The urgency sections are urgency_low, urgency_normal, urgency_critical for low, normal and critical urgency respectively.
See the example configuration file for examples.
The flags for setting the colors notifications of different urgencies have been removed. See issue #328 in the bug tracker for discussions (See REPORTING BUGS).
Where icon is a path to an image file containing the icon.
See COLORS for the value format.
See COLORS for the value format.
See COLORS for the value format.
See COLORS for more information
Dunst now contains a command line control command that can be used to interact with it. It supports all functions previously done only via keyboard shortcuts but also has a lot of extra functionality. For more information, see dunstctl(1).
Dunst saves a number of notifications (specified by history_length) in memory. These notifications can be recalled (i.e. redisplayed) by calling dunstctl history (see dunstctl(1)). Whether these notifications will time out like if they have been just send depends on the value of the sticky_history setting. Actions are invalidated once the notification is closed, so you cannot execute that action when you bring back a notification from history.
Past notifications are redisplayed in a first-in-last-out order, meaning that pressing the history key once will bring up the most recent notification that had been closed/timed out.
Dunst has Wayland support since version 1.6.0. Because the Wayland protocol is more focused on security, some things that are possible in X11 are not possible in Wayland. Those differences are reflected in the configuration. The main things that change are that dunst on Wayland cannot use global hotkeys (they are deprecated anyways, use dunstctl).
Some dunst features on wayland might need your compositor to support a certain protocol. Dunst will warn you if an optional feature isn't supported and will disable the corresponding functionality.
Fullscreen detection works on wayland with some limitations (see fullscreen). If you want notifications to appear over fullscreen windows, set layer = overlay in the global options.
Note that the same limitations exist when using xwayland. If something doesn't quite work in Wayland, please file a bug report. In the mean time, you can try if the X11 output does work on wayland. Use force_xwayland = true for that.
If you have your dunst notifications on the same side of your display as your status bar, you might notice that your notifications appear a bit higher or lower than on X11. This is because the notification cannot be placed on top of your status bar. The notifications are placed relative to your status bar, making them appear higher or lower by the height of your status bar. We cannot do anything about that behavior.
Rules allow the conditional modification of notifications. They can be located in a section with any name, even the special sections. The special sections do not allow filters to be added, since they have implied filters by default.
There are 2 parts in configuring a rule: Defining the filters that controls when a rule should apply and then the actions that should be taken when the rule is matched. It's also possible to not specify any filters, in which case the rule will match all notifications.
Rules are applied in order of appearance. Beware: if a notification is changed by a rule, it may affect if it's being matched by a later rule.
For filtering rules that filter based on strings you can use regular expressions. It's recommended to set enable_posix_regex to true. You can then use the POSIX Extended Regular Expression syntax: https://en.m.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions.
Notifications can be matched for any of the following attributes.
See "set_transient" for more details about this attribute.
See "override_dbus_timeout" for more details about this attribute.
See set_stack_tag for more information about stack tags.
"msg_urgency" is the urgency of the notification, it is named so to not conflict with trying to modify the urgency.
Instead of the appname filter, it's recommended to use the desktop_entry filter.
To define a matching rule simply assign the specified value to the value that should be matched, for example:
appname="notify-send"
Matches only messages that were send via notify-send. If multiple filter expressions are present, all of them have to match for the rule to be applied (logical AND).
Shell-like globing is supported.
This attribute specifies how notifications are handled if a fullscreen window is focused. By default it's set to show so notifications are being shown.
Other possible values are delay: Already shown notifications are continued to be displayed until they are dismissed or time out but new notifications will be held back and displayed when the focus to the fullscreen window is lost.
Or pushback which is equivalent to delay with the difference that already existing notifications are paused and hidden until the focus to the fullscreen window is lost.
On wayland, if follow is set to mouse or keyboard, the output where the notification is located cannot be determined. So dunst will delay or pushback if any of the outputs is fullscreen. Since the fullscreen protocol is fairly new, you will need a recent version of a compositor that supports it. At the time of writing, you will need the git version of sway. See also layer to change if notifications appear above fullscreen windows in Wayland.
Default: show
When using recursive icon lookup (see enable_recursive_icon_lookup), all icons from a theme will be this size.
If icon_position is set to off, this setting is ignored.
Set to 0 to disable icon downscaling.
If both min_icon_size and max_icon_size are enabled, the latter gets the last say.
If icon_position is set to off, this setting is ignored.
The stack tag can be set by the client with the 'synchronous', 'private-synchronous' 'x-canonical-private-synchronous' or the 'x-dunst-stack-tag' hints.
By default notifications are _not_ considered transient but clients can set the value of this by specifying the 'transient' hint when sending notifications.
IMPORTANT NOTE: This currently DOES NOT re-apply the attributes from the urgency_* sections. The changed urgency will only be visible in rules defined later. Use "msg_urgency" to match it.
Default: "default"
It's important to note that markup in the format option will be parsed regardless of what this is set to.
Possible values:
<b>bold</b>
<i>italic</i>
<s>strikethrough</s>
<u>underline</u>
For a complete reference see <https://docs.gtk.org/Pango/pango_markup.html>
Dunst will try to strip the markup but the parsing is simplistic so using this option outside of matching rules for specific applications IS GREATLY DISCOURAGED.
See RULES
As with the filtering attributes, each one corresponds to the respective notification attribute to be modified.
As with filtering, to make a rule modify an attribute simply assign it in the rule definition.
If the format is set to an empty string, the notification will not be suppressed.
Within rules you can specify a script to be run every time the rule is matched by assigning the 'script' option to the name of the script to be run.
When the script is called details of the notification that triggered it will be passed via environment variables. The following variables are available: DUNST_APP_NAME, DUNST_SUMMARY, DUNST_BODY, DUNST_ICON_PATH, DUNST_URGENCY, DUNST_ID, DUNST_PROGRESS, DUNST_CATEGORY, DUNST_STACK_TAG, DUNST_URLS, DUNST_TIMEOUT, DUNST_TIMESTAMP, DUNST_DESKTOP_ENTRY, and DUNST_STACK_TAG.
Another, less recommended way to get notifcations details from a script is via command line parameters. These are passed to the script in the following order: appname, summary, body, icon_path, urgency.
Where DUNST_ICON_PATH or icon_path is the absolute path to the icon file if there is one. DUNST_URGENCY or urgency is one of "LOW", "NORMAL" or "CRITICAL". DUNST_URLS is a newline-separated list of urls associated with the notification.
Note that some variables may be empty.
If the notification is suppressed, the script will not be run unless always_run_scripts is set to true.
If '~/' occurs at the beginning of the script parameter, it will get replaced by the users' home directory. If the value is not an absolute path, the directories in the PATH variable will be searched for an executable of the same name.
Colors are interpreted as X11 color values. This includes both verbatim color names such as "Yellow", "Blue", "White", etc as well as #RGB and #RRGGBB values.
You may also specify a transparency component in #RGBA or #RRGGBBAA format.
NOTE: '#' is interpreted as a comment, to use it the entire value needs to be in quotes like so: separator_color="#123456"
dunst is able to get different colors for a message via notify-send. In order to do that you have to add a hint via the -h option. The progress value can be set with a hint, too.
All hints
See RULES for more detailed explanations for some options.
Examples
Dunst allows notifiers (i.e.: programs that send the notifications) to specify actions. Dunst has support for both displaying indicators for these, and interacting with these actions.
If "show_indicators" is true and a notification has an action, an "(A)" will be prepended to the notification format. Likewise, an "(U)" is prepended to notifications with URLs. It is possible to interact with notifications that have actions regardless of this setting, though it may not be obvious which notifications HAVE actions.
The "context" keybinding is used to interact with these actions, by showing a menu of possible actions. This feature requires "dmenu" or a dmenu drop-in replacement present.
Alternatively, you can invoke an action with a middle click on the notification. If there is exactly one associated action, or one is marked as default, that one is invoked. If there are multiple, the context menu is shown. The same applies to URLs when there are no actions.
A time can be any decimal integer value suffixed with a time unit. If no unit given, seconds ("s") is taken as default.
Time units understood by dunst are "ms", "s", "m", "h" and "d".
Example time: "1000ms" "10m"
Written by Sascha Kruse <knopwob@googlemail.com>
Bugs and suggestions should be reported on GitHub at https://github.com/dunst-project/dunst/issues
Copyright 2013 Sascha Kruse and contributors (see LICENSE for licensing information)
If you feel that copyrights are violated, please send me an email.
| 2022-11-25 | 1.9.0 (2022-06-27) |