FreeBSD Manual Pages

home | help

dunst(5) Dunst Reference dunst(5)

NAME
dunstrc - dunst configuration file

DESCRIPTION
The configuration is divided into sections in an ini-like format. Every
section starts 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 change 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
its properties. There are filtering rules and modifying rules.
Filtering rules specify what notifications the rule applies to.
Modifying rules specify changes to the matching notifications. Some
special sections have implied filters that cannot be changed. For
example, the "global" section has no filters: it applies to all
notifications.

See RULES for more details.

The "experimental" section contains experimental and unstable settings.
These options can change in breaking ways between releases. If you
find a problem with these new features, make sure to report it.

Global section
default_pause_level (values: [0-100], default: 0)
Specify a pause level to be set on dunst startup. Notifications are
only shown if their urgency level is higher than the pause level.
See override_pause_level for more information.

monitor (default: 0)
Specifies on which monitor the notifications should be displayed
in, either by name or by number, starting from 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 them 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.

enable_posix_regex (default: false)
When set to true (recommended), you can use POSIX regular
expressions for filtering rules. It uses the POSIX Extended Regular
Expression syntax:
https://en.m.wikibooks.org/wiki/Regular_Expressions/POSIX-Extended_Regular_Expressions.

If this is set to false (not recommended), dunst will use
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".

geometry DEPRECATED
This setting is deprecated and removed. It's split up into width,
height, origin, notification_limit and offset. For quickly
transitioning to the new syntax, you can take the numbers from your
old geometry config as follows:
geometry = <width>x<height>+<offset>

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

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

Examples:

height = 300 # constant height of 300
height = (0, 300) # height between 0 and 300

Note that unlike width, different notifications can have diffrent
height values.

Dunst v1.11 and older do not support a dynamic height and height
accepts a single value whose behaviour is equivalent to (0, value).

notification_limit (default: 20)
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), default: (10, 50))
Respectively the horizontal and vertical offset in pixels from the
corner of the screen specified by origin. A negative offset will
lead to the notification being off screen.

Examples:

origin = top-right
offset = (10, 300) # a margin of 10 pixels from the right and 300 pixels from the top

Dunst v1.11 and older use the syntax NxN instead (X offset x Y
offset). For backwards compatibility this syntax is also accepted.

offset = 10x300

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_horizontal_alignment (values: [left/center/right],
default: center)
Horizontal alignment of the progress bar. The progress bar will
always keep a distance of horizontal_padding from the edge of the
notification.

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.

progress_bar_corner_radius (default: 0)
The corner radius of the progress bar in pixels. Gives the progress
bar rounded corners. Set to 0 to disable.

This setting will be ignored if progress_bar_corners is set to
none.

progress_bar_corners (default: all)
Define which corners to round when drawing the progress bar. If
progress_bar_corner_radius is set to 0 this option will be ignored.

See the corners setting for the value format.

icon_corner_radius (default: 0)
The corner radius of the icon image in pixels. Gives the icon
rounded corners. Set to 0 to disable.

This setting will be ignored if icon_corners is set to none.

icon_corners (default: all)
Define which corners to round when drawing the icon image. If
icon_corner_radius is set to 0 this option will be ignored.

See the corners setting for the value format.

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.

This will affect the whole window. To make only parts of a window
transparent set the alpha channel in a color, see COLORS.

To make windows transparent on wayland, set the transparent 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. This
setting will be ignored if gap_size is greater than 0.

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.

gap_size (default: 0)
Size of gap to display between notifications.

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.

separator_color (values: [auto/foreground/frame/#RRGGBB], default:
frame)
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/id/urgency_ascending/urgency_descending/update], default:
true)
If set to true or urgency_descending, display notifications with
higher urgency above the others. critical first, then normal, then
low.

If set to false or id, sort notifications by id.

If set to urgency_ascending, notifications are sorted by urgency,
low first, then normal, then critical.

If set to update, notifications are sorted by their update_time.
So the most recent is always at the top. This means that if you set
sort to update, and stack_duplicates to true, the duplicate will
always be at the top.

When the notification window is at the bottom of the screen, this
order is automatically reversed.

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 (values: [bottom/top/overlay], default: overlay) (Wayland only)
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.

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.

This setting will be ignored if dunst was compiled without X11
support.

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. More
information on the string format can be found here
https://docs.gtk.org/Pango/type_func.FontDescription.from_string.html.

line_height (default: 0)
The amount of extra spacing between text lines in pixels. Set to 0
to disable.

format (default: "%s\n%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 '&amp;'.

If '\n' or '\t' is present anywhere in the format, it will be
replaced with a literal newline or tab respectively.

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

%a appname
%s summary
%b body
%c category
%S stack_tag
%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.

vertical_alignment (values: [top/center/bottom], default: center)
Defines how the text and icon should be aligned vertically within
the notification.

show_age_threshold (default: 60)
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_path (default:
"/usr/local/share/icons/gnome/16x16/status/:/usr/local/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 icon_path search.

icon_theme (default: "Adwaita", example: "Adwaita, breeze")
Comma-separated list of names of 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/local/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 not enabled by default. See
enable_recursive_icon_lookup for how to enable it.

enable_recursive_icon_lookup (default: false)
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. 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 [global] 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/local/bin/dmenu -p dunst")
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/local/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") (X11 only)
Defines the title (_NET_WM_NAME property) of notification windows
spawned by dunst.

There should be no need to modify this setting for regular use.

class (default: "Dunst") (X11 only)
Defines the class (WM_CLASS first part) of notification windows
spawned by dunst.

There should be no need to modify this setting for regular use.

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, unless if gaps are enabled
(see gaps_size).

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.

This setting will be ignored if corners is set to none.

corners (values:
[none/all/bottom-right/bottom-left/top-right/top-left/top/bottom/left/right],
default: all)
Comma-separated list of the corners to round when drawing the
window.

If the corner radius is set to 0 this option will be ignored.

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. A list of values, separated by commas, can be
specified for multiple actions to be executed in sequence.

Defaults:

• "mouse_left_click=close_current"

• "mouse_middle_click=do_action, remove_current"

• "mouse_right_click=close_all"

none
Don't do anything.

do_action
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
Close current notification.

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

override_pause_level (values: [0-100], default: 0)
A notification will appear whenever notification's
override_pause_level is greater than the paused level. Setting
this to values other than 0 allows you to create partial pause
modes, where more urgent notifications get through, but less urgent
stay paused.

For example, when you can set a low battery notification's
override_pause_level to 60 and then set dunst's pause level to 60.
This will cause dunst to only show battery level notification (and
other notifications with override_pause_level >= 60), while
suspending others.

Keyboard shortcuts (X11 only)
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.

Wayland does not allow applications to listen to global keyboard
events, so this feature can be implemented only for X.

close
Specifies the keyboard shortcut for closing a notification.

close_all
Specifies the keyboard shortcut for closing all currently displayed
notifications.

history
Specifies the keyboard shortcut for recalling a single notification
from history.

context
Specifies the keyboard shortcut that opens the context menu.

Urgency sections
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.

Old version of dunst allowed changing the colors of different urgencies
through command line options. This has been long removed in favour of
RULES, see issue #328.

Experimental section
per_monitor_dpi (default: false)
Use different DPI for each monitor. This setting is currently
implemented only for X11.

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

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

WAYLAND
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, use dunstctl instead.

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.

Note that dunst creates a "desktop layer" using the layer shell
protocol and not a regular Wayland window. This has some limitations
like stated above. For example you can't set a window title/class.

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

'global'
No filters, matches all notifications.

'urgency_low', 'urgency_normal' and 'urgency_critical'
Matches low, normal or critical urgency respectively.

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.

filtering
With filtering rules you can match notifications to apply rules to
only a subset of notifications.

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.

A matching rule is made by assigning a filter attribute to the
value you want to match. Shell-like globbing is supported when
matching values.

If multiple filter expressions are present, all of them have to
match for the rule to be applied (logical AND).

An example of rule that only operates on messages sent by
notify-send is:

appname="notify-send"

The allowed attributes are listed below.

"appname" (see also desktop_entry)
The name of the application as reported by the client. Be aware
that the name can often differ depending on the locale used.

It's recommended to use the "desktop_entry" filter instead.

"body"
The body of the notification

"category"
The category of the notification as defined by the notification
spec. See
https://specifications.freedesktop.org/notification-spec/latest/categories.html.

"desktop_entry"
GLib based applications export their desktop-entry name. In
comparison to the appname, the desktop-entry won't get
localized.

"icon"
The icon of the notification in the form of a file path. Can be
empty if no icon is available or a raw icon is used instead.
This setting is not to be confused with the icon setting in the
urgency section.

"match_transient"
Match if the notification has been declared as transient by the
client or by some other rule.

See "set_transient" for more details about this attribute.

"match_dbus_timeout"
Matches the dbus timeout of the notification as set by the
client or by some other rule.

See "override_dbus_timeout" for more details about this
attribute.

"msg_urgency"
Matches the urgency of the notification as set by the client or
by some other rule.

It is named so to not conflict with trying to modify the
urgency.

"stack_tag"
Matches the stack tag of the notification as set by the client
or by some other rule.

See set_stack_tag for more information about stack tags.

"summary"
Matches the summary, 'title', of the notification.

modifying
A modifying rule, similarly to a filtering one, is made by
assigning a value to a notification attribute in the rule
definition.

The following attributes can be overridden:

"background"
The background color of the notification. See COLORS for
possible values.

"foreground"
The foreground color of the notification. See COLORS for
possible values.

"highlight"
The highlight color of the notification. This color is used for
coloring the progress bar. See COLORS for possible values.

You can also set additional color values (as a comma-separated
list) to define a linear gradient spanning all the length of
the progress bar.

"format"
Equivalent to the "format" setting.

"frame_color"
The frame color color of the notification. See COLORS for
possible values.

"fullscreen" (values: [delay/show/pushback], default: show)
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.

"min_icon_size" (default: 32)
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.

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.

"max_icon_size" (default: 128)
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.

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.

"new_icon"
Updates the icon of the notification, it should be a path or a
name for a valid image. This overrides the icon that was sent
with dunstify or another notification tool. Expansion of the
argument is carried out using wordexp(3) with command
substitution disabled.

"icon_position" (values: [left/right/top/off], default: left)
Defines the position of the icon in the notification window.
Setting it to off disables icons.

"default_icon"
Sets the default icon of the notification, it should be a path
or a name for a valid image. This does not override the icon
that was sent with dunstify or another notification tool.
Expansion of the argument is carried out using wordexp(3) with
command substitution disabled.

"set_stack_tag"
Sets the stack tag for the notification, notifications with the
same (non-empty) stack tag and the same appid will replace
each-other so only the newest one is visible. This can be
useful for example in volume or brightness notifications where
you only want one of the same type visible.

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.

"set_transient"
Sets whether the notification is considered transient.
Transient notifications will bypass the idle_threshold setting.

By default notifications are _not_ considered transient but
clients can set the value of this by specifying the 'transient'
hint when sending notifications.

"set_category"
Sets the category of the notification. For a list of standard
categories see
https://specifications.freedesktop.org/notification-spec/latest/categories.html.

"timeout"
Equivalent to the "timeout" setting in the urgency sections.

"override_dbus_timeout"
Overrides the timeout specified in dbus. This takes precedence
over "timeout".

"urgency"
This sets the notification urgency.

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.

"skip_display"
Setting this to true will prevent the notification from being
displayed initially but will be saved in history for later
viewing.

"history_ignore"
Setting this to true will display the notification initially,
but stop it from being recalled via the history.

"action_name" (default: "default")
Sets the name of the action to be invoked on do_action. If not
specified, the action set as default action or the only
available action will be invoked.

"word_wrap" (values: [true/false], default: true)
Specifies whether to wrap the text if the lines get longer than
the maximum notification width. 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. If the text doesn't
fit in the window, it will be ellipsize according to ellipsize.

"ellipsize" (values: [start/middle/end], default: middle)
Specifies where truncated lines should be ellipsized.

"alignment" (values: [left/center/right], default: left)
Defines how the text should be aligned within the notification.

"hide_text" (values: [true/false], default: false)
Setting this to true will skip displaying any text related to
the notification. The notification icon and progress bar will
still be displayed. This option may be useful for notifications
where an icon or progress bar may be sufficient information for
the notification, such as audio volume or brightness level.

"markup" (values: [full/strip/no], default: no)
Defines how markup in notifications is handled.

It's important to note that markup in the format option will be
parsed regardless of what this is set to.

Possible values:

full
Allow a small subset of html markup in notifications

bold
italic
<s>strikethrough</s>
underline

For a complete reference see
https://docs.gtk.org/Pango/pango_markup.html.

strip
This setting is provided for compatibility with some broken
clients that send markup even though it's not enabled on
the server.

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 for matching specific broken clients.

no Disable markup parsing, incoming notifications will be
treated as plain text. Dunst will not advertise that it can
parse markup if this is set as a global setting.

SCRIPTING
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_script is set to true.

The script parameter is expanded according to wordexp(3) with command
substitution disabled. If the expanded value is not an absolute path,
the directories in the PATH variable will be searched for an executable
of the same name.

COLORS
Colors are values with the format #RGB or #RRGGBB.

You may also specify a transparency component by using the format #RGBA
or #RRGGBBAA.

NOTE: '#' is interpreted as a comment, to use it the entire value needs
to be quoted. For example:

separator_color="#123456"

NOTIFY-SEND HINTS
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.

Note: Dunstify is compatible with notify-send and all of these settings
work the same way.

All the accepted hints are listed below.

See RULES for more detailed explanations for some options.

fgcolor (type: string)
Foreground color.

bgcolor (type: string)
Background color.

frcolor (type: string)
Frame color.

hlcolor (type: string or string array)
Highlight color.

value (type: int or uint)
Progress value.

image-path (type: string)
Icon name. This may be a path or just the icon name.

The alias image_path is also supported.

image-data (type: variant)
A stream of raw image data.

The aliases image_data and icon_data are also supported.

category (type: string)
The category.

desktop-entry (type: string)
The desktop entry.

transient (type: int or boolean)
The transient value.

x-dunst-stack-tag (type: string)
The stack tag of the notification. A tagged notification will
replace an earlier notification with the same tag.

x-canonical-private-synchronous (type: string)
Alias for x-dunst-stack-tag.

Some examples:

notify-send -h string:fgcolor:#ff4444 "hello"

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

notify-send -h int:value:42 "Working ..."

notify-send -h string:x-canonical-private-synchronous:volume "Muted"

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

TIME FORMAT
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".

AUTHORS
Written by Sascha Kruse <knopwob@googlemail.com>.

REPORTING BUGS
Bugs and suggestions should be reported on GitHub at
https://github.com/dunst-project/dunst/issues.

If you feel that copyrights are violated, please send me an email.

SEE ALSO
dunst(1), dunstctl(1), dmenu(1), notify-send(1), dunstify(1)

1.13.0 (2025-08-04) 2025-11-01 dunst(5)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dunst&sektion=5&manpath=FreeBSD+15.0-RELEASE+and+Ports>

home | help

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages