Manpages - dunst.5

monitor (default: 0)

Specifies on which monitor the notifications should be displayed in, count starts at 0. See the follow setting.

follow (values: [none/mouse/keyboard] default: none)

Defines where the notifications should be placed in a multi-monitor setup. All values except none override the monitor setting. 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.

none

The notifications will be placed on the monitor specified by the monitor setting.

mouse

The notifications will be placed on the monitor that the mouse is currently in.

keyboard

The notifications will be placed on the monitor that contains the window with keyboard focus.

geometry DEPRECATED

This setting is deprecated and removed. It’s split up into width, height, origin, notification_limit and offset.

width

The width of the notification window in pixels. This can be a single number to specify a constant width or two numbers for the minimum and maximum width. The notification will expand from the minimum width as neccesary. 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).

height

The maximum height of a single notification.

notification_limit (default: 0)

The number of notifications that can appear at one time. When this limit is reached any additional notifications will be queued and displayed when the currently displayed ones either time out or are manually dismissed. The value 0 means no limit. If indicate_hidden is true, then the specified limit is reduced by 1 and the last notification is a message informing how many hidden notifications are waiting to be displayed. See the indicate_hidden entry for more information.

origin (default: top-right)

The origin of the notification window on the screen. It can then be moved with offset. Origin can be one of: top-left top-center top-right bottom-left bottom-center bottom-right left-center center right-center

offset format: (horizontal, vertical)

Respectively the horizontal and vertical offset in pixels from the corner of the screen specified by origin. Both values should always be positive or zero. Examples: origin = top-right offset = 10x300 # a margin of 10 pixels from the right and 300 pixels from the top

scale (default: 0, X11 only)

Specifies a scale factor for dimensions to adapt notifications to HiDPI screens. This scales the notification geometry and it’s contents. It is not recommended to use a fractional scaling factor, as this may result in things being one pixel off. Try to use a whole number scaling factor and adjust the font size and other sizes as needed. If 0 is specified, the scale factor is auto-detected.

progress_bar (values: [true/false], default: true)

When an integer value is passed to dunst as a hint (see NOTIFY-SEND), a progress bar will be drawn at the bottom of the notification. This behavior can be turned off by setting this setting to false.

progress_bar_height (default: 10)

The height of the progress bar in pixel. This includes the frame. Make sure this value is bigger than twice the frame width.

progress_bar_min_width (default: 150)

The minimum width of the progress bar in pixels. The notification is rescaled to fit the bar.

progress_bar_max_width (default: 300)

The maximum width of the progress bar in pixels. The notification is resized to fit the progress bar.

progress_bar_frame_width (default: 1)

The frame width of the progress bar in pixels. This value should be smaller than half of the progress bar height.

indicate_hidden (values: [true/false], default: true)

If this is set to true, a notification indicating how many notifications are not being displayed due to the notification limit (see notification_limit) will be shown in place of the last notification slot. 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.

transparency (default: 0) (X11 only)

A 0-100 range on how transparent the notification window should be, with 0 being fully opaque and 100 invisible. 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.

separator_height (default: 2)

The height in pixels of the separator between notifications, if set to 0 there will be no separating line between notifications.

padding (default: 8)

The distance in pixels from the content to the separator/border of the window in the vertical axis

horizontal_padding (default: 8)

The distance in pixels from the content to the border of the window in the horizontal axis

text_icon_padding (default: 0)

The distance in pixels from the text to the icon (or vice versa) in the horizontal axis. 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

frame_width (default: 3)

Defines width in pixels of frame around the notification window. Set to 0 to disable.

(no term)

separator_color (values: [auto/foreground/frame/#RRGGBB] default: auto) :: Sets the color of the separator line between two notifications.

auto

Dunst tries to find a color that fits the rest of the notification color scheme automatically.

foreground

The color will be set to the same as the foreground color of the topmost notification that’s being separated.

frame

The color will be set to the frame color of the notification with the highest urgency between the 2 notifications that are being separated.

anything else

Any other value is interpreted as a color, see COLORS

sort (values: [true/false], default: true)

If set to true, display notifications with higher urgency above the others.

idle_threshold (default: 0)

Don’t timeout notifications if user is idle longer than this time. See TIME FORMAT for valid times. 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.

layer (Wayland only)

One of bottom, top or overlay. 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

(no term)

force_xwayland (values: [true/false], default: false) (Wayland only) :: Force the use of X11 output, even on a wayland compositor. This setting has no effect when not using a Wayland compositor.

font (default: “Monospace 8”)

Defines the font or font set used. Optionally set the size as a decimal number after the font name and space. Multiple font options can be separated with commas. This options is parsed as a Pango font description.

line_height (default: 0)

The amount of extra spacing between text lines in pixels. Set to 0 to disable.

format (default: “%s %b”)

Specifies how the various attributes of the notification should be formatted on the notification window. 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.

%a appname

%s summary

%b body

%i iconname (including its path)

%I iconname (without its path)

%p progress value ([ 0%] to [100%])

%n progress value without any extra characters

%% Literal %

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.

(no term)

vertical_alignment (values: [top/center/bottom], default: center) :: Defines how the text and icon should be aligned vertically within the notification. If icons are disabled, this option has no effect.

show_age_threshold (default: -1)

Show age of message if message is older than this time. See TIME FORMAT for valid times. Set to -1 to disable.

ignore_newline (values: [true/false], default: false)

If set to true, replace newline characters in notifications with whitespace.

stack_duplicates (values: [true/false], default: true)

If set to true, duplicate notifications will be stacked together instead of being displayed separately. Two notifications are considered duplicate if the name of the program that sent it, summary, body, icon and urgency are all identical.

hide_duplicate_count (values: [true/false], default: false)

Hide the count of stacked duplicate notifications.

show_indicators (values: [true/false], default: true)

Show an indicator if a notification contains actions and/or open-able URLs. See ACTIONS below for further details.

icon_position (values: [left/right/off], default: off)

Defines the position of the icon in the notification window. Setting it to off disables icons.

min_icon_size (default: 0)

Defines the minimum size in pixels for the icons. If the icon is larger than or equal to the specified value it won’t be affected. If it’s smaller then it will be scaled up so that the smaller axis is equivalent to the specified size. Set to 0 to disable icon upscaling. (default) If icon_position is set to off, this setting is ignored.

max_icon_size (default: 0)

Defines the maximum size in pixels for the icons. If the icon is smaller than or equal to the specified value it won’t be affected. If it’s larger then it will be scaled down so that the larger axis is equivalent to the specified size. Set to 0 to disable icon downscaling. (default) 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.

(no term)

icon_path (default: “usr/share/icons/gnome/16x16/status:/usr/share/icons/gnome/16x16/devices/”) :: Can be set to a colon-separated list of paths to search for icons to use with notifications. 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.

(no term)

icon_theme (default: “Adwaita”, example: “Adwaita, breeze”) Experimental :: Comma-separated of names of the the themes to use for looking up icons. This has to be the name of the directory in which the theme is located, not the human-friendly name of the theme. So for example, the theme Breeze Dark is located in /usr/share/icons/breeze-dark. In this case you have to set the theme to breeze-dark. 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.

enable_recursive_icon_lookup (default: false) Experimental

This setting enables the new icon lookup method. This new system will eventually be the old icon lookup. Currently icons are looked up in the icon_path and scaled according to min_icon_size and max_icon_size. 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 and icon_size to the icon size 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.

sticky_history (values: [true/false], default: true)

If set to true, notifications that have been recalled from history will not time out automatically.

history_length (default: 20)

Maximum number of notifications that will be kept in history. After that limit is reached, older notifications will be deleted once a new one arrives. See HISTORY.

dmenu (default: “/usr/bin/dmenu”)

The command that will be run when opening the context menu. Should be either a dmenu command or a dmenu-compatible menu.

browser (default: “/usr/bin/xdg-open”)

The command that will be run when opening a URL. The URL to be opened will be appended to the end of the value of this setting.

always_run_script (values: [true/false] default: true]

Always run rule-defined scripts, even if the notification is suppressed with format = “”. See SCRIPTING.

title (default: “Dunst”)

Defines the title of notification windows spawned by dunst. (_NET_WM_NAME property). There should be no need to modify this setting for regular use.

class (default: “Dunst”)

Defines the class of notification windows spawned by dunst. (First part of WM_CLASS). There should be no need to modify this setting for regular use.

(no term)

force_xinerama (values: [true/false], default: false) (X11 only) :: Use the Xinerama extension instead of RandR for multi-monitor support. This setting is provided for compatibility with older nVidia drivers that do not support RandR and using it on systems that support RandR is highly discouraged. 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.

corner_radius (default: 0)

Define the corner radius in pixels. A corner radius of 0 will result in rectangular shaped notifications. 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.

(no term)

mouse_left/middle/right_click (values: [none/do_action/close_current/close_all/context/context_all]) :: Defines action of mouse click. A touch input in Wayland acts as a mouse left click.

none

Don’t do anything.

do_action (default for mouse_middle_click)

Invoke the action determined by the action_name rule. If there is no such action, open the context menu.

open_url

If the notification has exactly one url, open it. If there are multiple ones, open the context menu.

close_current (default for mouse_left_click)

Close current notification.

close_all (default for mouse_right_click)

Close all notifications.

context

Open context menu for the notification.

context_all

Open context menu for all notifications.

ignore_dbusclose (default: false)

Ignore the dbus closeNotification message. This is useful to enforce the timeout set by dunst configuration. Without this parameter, an application may close the notification sent before the user defined timeout.

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.

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).

-li/ni/ci icon DEPRECATED

Defines the icon for low, normal and critical notifications respectively. This setting will be replaced by the default_icon setting, so it’s recommended to replace it as soon as possible. Where icon is a path to an image file containing the icon.

-lf/nf/cf color

Defines the foreground color for low, normal and critical notifications respectively. See COLORS for the value format.

-lb/nb/cb color

Defines the background color for low, normal and critical notifications respectively. See COLORS for the value format.

-lh/nh/ch color

Defines the highlight color for low, normal and critical notifications respectively. See COLORS for the value format.

-lfr/nfr/cfr color

Defines the frame color for low, normal and critical notifications respectively. See COLORS for more information

-lto/nto/cto secs

Defines the timeout time for low, normal and critical notifications respectively. See TIME FORMAT for valid times.

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.

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.

fgcolor: Foreground cololor

bgcolor: Background color

frcolor: Frame color

hlcolor: Highlight color

value: Progress value.

image-path: Icon name. This may be a path or just the icon name.

image-data: A stream of raw image data.

category: The category.

desktop-entry: The desktop entry.

transient: The transient value.

Examples

notify-send -h string:fgcolor:#ff4444

(no term)

notify-send -h string:bgcolor:#4444ff -h string:fgcolor:#ff4444 -h string:frcolor:#44ff44 ::

notify-send -h int:value:42 “Working …”