| dunst(1) | Dunst Reference | dunst(1) |
dunst - A customizable and lightweight notification-daemon
dunst [-conf file] [-font font] [-geometry geom] [-format fmt] [-follow mode] [-monitor n] [-history_length n] ...
Dunst is a highly configurable and lightweight notification daemon.
An example configuration file is included (usually /usr/share/doc/dunst/dunstrc.gz). To change the configuration, copy this file to ~/.config/dunst/dunstrc and edit it accordingly.
The configuration is divided into sections in an ini-like format. The 'global' section contains most general settings while the 'shortcuts' sections contains all keyboard configuration and the 'experimental' section all the features that have not yet been tested thoroughly.
Any section that is not one of the above is assumed to be a rule, see RULES for more details.
For backwards compatibility reasons the section name 'frame' is considered bound and can't be used as a rule.
Each configuration option in the global section can be overridden from the command line by adding a single dash in front of it's name. For example the font option can be overridden by running
$ dunst -font "LiberationSans Mono 4"
Configuration options that take boolean values can only currently be set to "true" through the command line via the same method. e.g.
$ dunst -shrink
This is a known limitation of the way command line parameters are parsed and will be changed in the future.
Available settings per section:
The physical(pixel) height of the notifications vary depending on the number of lines that need to be displayed.
See notification_height for changing the physical height.
It's important to note that the positive and negative sign DOES affect the position even if the offset is 0. For example, a horizontal offset of +0 puts the notification on the left border of the screen while a horizontal offset of -0 at the right border. The same goes for the vertical offset.
Meaning that if this is enabled the number of visible notifications will be 1 less than what is specified in geometry, the last slot will be taken by the hidden count.
This is used mainly in order to have the shrinking benefit of dynamic width (see geometry) while also having an upper bound on how long a notification can get before wrapping.
This setting will only work if a compositor is running.
Set to 0 to disable.
Transient notifications will ignore this setting and timeout anyway. Use a rule overwriting with 'set_transient = no' to disable this behavior.
This options is parsed as a Pango font description.
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 <http://developer.gnome.org/pango/stable/PangoMarkupFormat.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
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.
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.
If it's set to false, long lines will be truncated an ellipsised.
If it's set to true, long lines will be broken into multiple lines expanding the notification window height as necessary for them to fit.
Two notifications are considered duplicate if the name of the program that sent it, summary, body, icon and urgency are all identical.
Set to 0 to disable icon scaling. (default)
If icon_position is set to off, this setting is ignored.
Dunst doesn't currently do any type of icon lookup outside of these directories.
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.
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.
Specifies the keyboard shortcut for closing a notification.
Specifies the keyboard shortcut for closing all currently displayed notifications.
Specifies the keyboard shortcut for recalling a single notification from history.
Specifies the keyboard shortcut that opens the context menu.
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, 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.
Additionally, you can override these settings via the following command line flags:
Please note these flags may be removed in the future. 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 more information
Dunst saves a number of notifications (specified by history_length) in memory. These notifications can be recalled (i.e. redesiplayed) by pressing the history_key (see the shortcuts section), whether these notifications will time out like if they have been just send depends on the value of the sticky_history setting.
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.
Rules allow the conditional modification of notifications. They are defined by creating a section in the configuration file that has any name that is not already used internally (i.e. any name other than 'global', 'experimental', 'frame', 'shortcuts', 'urgency_low', 'urgency_normal' and 'urgency_critical').
There are 2 parts in configuring a rule: Defining the filters that control when a rule should apply and then the actions that should be taken when the rule is matched.
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.
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 command line parameters in the following order: appname, summary, body, icon, urgency.
Where icon is the absolute path to the icon file if there is one and urgency is one of "LOW", "NORMAL" or "CRITICAL".
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.
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.
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 preneded 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"
Dunst can be paused by sending a notification with a summary of "DUNST_COMMAND_PAUSE" and resumed with a summary of "DUNST_COMMAND_RESUME". Alternatively you can send SIGUSR1 and SIGUSR2 to pause and unpause respectively. For Example:
When paused dunst will not display any notifications but keep all notifications in a queue. This can for example be wrapped around a screen locker (i3lock, slock) to prevent flickering of notifications through the lock and to read all missed notifications after returning to the computer.
$XDG_CONFIG_HOME/dunst/dunstrc
-or-
$HOME/.config/dunst/dunstrc
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.
| 2018-10-14 | 1.3.2 (2018-05-06) |