dunst(5)

📦
version 1.13.2 · 10 versions
, in fedora 43, fedora 44

✨ dunst(5) — Dunst Reference ✨

okay bestie, gather round, because this is the dunst(5) page and it's literally the whole dunst configuration bible 🫶 settle in, grab a strawberry 🍓, and let's get into it.

🌸 NAME 🌸

dunstrc — the dunst configuration file. that's it, that's the name, iconic 💅

💖 DESCRIPTION 💖

so the config is split into sections, in an ini-ish format. every section kicks off with the section's name wrapped in square brackets. after that comes a list of key-value pairs that set your actual settings. whitespace? purely cosmetic bestie, it changes nothing about the result.

the "global" section holds the general settings that apply to all of dunst. everything else can be specified via rules, and those rules can live in any section. rules can change a notification based on its properties, and there are two flavors:

  • filtering rules — these say which notifications the rule even applies to.
  • modifying rules — these say what changes happen to the notifications that match.

some special sections come with implied filters that you cannot change. for example, the "global" section has no filters at all — it applies to every single notification. periodt.

see RULES for the full tea.

the "experimental" section holds experimental and unstable settings. heads up: these options can change in breaking ways between releases 😭 so if you hit a problem with one of these new features, please make sure to report it!

🎀 Global section 🎀

  • default_pause_level (values: [0-100], default: 0) — sets a pause level for when dunst starts up. notifications only show if their urgency level is higher than the pause level. wanna know more? go peek at override_pause_level.
  • monitor (default: 0) — which monitor the notifications get displayed on, either by name or by number, counting from 0. also see the follow setting.
  • follow (values: [none/mouse/keyboard], default: none) — decides where notifications land in a multi-monitor setup. every value except none overrides the monitor setting.

on Wayland there's no difference between mouse and keyboard focus, bestie. when either one is used, the compositor picks an output for you. generally it'll be the output you last interacted with.

  • none — notifications go on the monitor specified by the monitor setting.
  • mouse — notifications go on the monitor your mouse is currently in.
  • keyboard — notifications go on the monitor containing the window with keyboard focus.

if you set this to false (not recommended, ngl), dunst falls back to fnmatch(3) for matching strings. dunst doesn't pass any flags to fnmatch, so you can't make use of extended patterns. sad.

the POSIX syntax is more powerful and will eventually become the default. the main differences between POSIX and fnmatch(3) are: POSIX uses .* for wildcards instead of *, and POSIX allows partial matches without needing wildcards. so the pattern abc will match every string that contains abc, like abcdef. cute right?

  • geometry DEPRECATED — this setting is deprecated and removed 💀 it got split up into width, height, origin, notification_limit and offset. if you wanna transition to the new syntax quickly, you can take the numbers from your old geometry config like this:
geometry = <width>x<height>+<offset>

and then in your new config set these 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 for a constant width, or two numbers for the minimum and maximum width. the notification expands from the minimum width as necessary.

examples:

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

if you set a width bigger than the screen, dunst clamps the width to the screen width. so if you want the notification to stretch the entire screen dynamically, you can set the width to a high enough number that none of your screens exceed (e.g. 10000) 👑

  • height — the height of each notification in pixels. this can be a single number for a constant height, or two numbers for the minimum and maximum width. the notification expands from the minimum height as necessary.

examples:

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

note that unlike width, different notifications can have different 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. once you hit this limit, any extra notifications get queued and shown when the currently displayed ones either time out or get manually dismissed. the value 0 means no limit at all. if indicate_hidden is true, then the specified limit gets reduced by 1 and the last notification becomes a message telling you how many hidden notifications are waiting to be displayed. see the indicate_hidden entry for more info.
  • origin (default: top-right) — the origin of the notification window on the screen. from there it can 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 its contents. it's not recommended to use a fractional scaling factor, because that 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 gets drawn at the bottom of the notification. you can turn this behavior off by setting this 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's specified by notification_limit — the last slot gets taken by the hidden count.

  • transparency (default: 0) (X11 only) — a 0-100 range for how transparent the notification window should be, with 0 being fully opaque and 100 invisible.

this affects the whole window. if you want only parts of a window transparent, set the alpha channel in a color instead, 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, bestie, so keep that in mind.

  • 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

okay so bestie, this next bit is just showing you that this:

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. Here's the tea:
    • 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: "<b>%s</b>\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>. Here's the cheat sheet:
    • %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/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 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/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/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/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]) — okay so this is literally just "what does a click even DO" 💅 You pick the action for each mouse button. Fun fact bestie: on Wayland a touch input acts as a mouse left click, slay. And you can throw a whole list of values at it separated by commas, and it'll run them in sequence, one after the other. ✨

Defaults:

  • "mouse_left_click=close_current"
  • "mouse_middle_click=do_action, remove_current"
  • "mouse_right_click=close_all"
  • none — do absolutely nothing. no thoughts, head empty 🫶
  • do_action — fire off the action that the action_name rule picked out. If there's no such action to be found? It opens the context menu instead. periodt.
  • open_url — if the notification has exactly one url, open it. If there's more than one, we open the context menu instead. no picking favourites here 😭
  • close_current — closes the current notification. bye bestie 🎀
  • close_all — closes every notification. clear the whole group chat.
  • context — opens the context menu for the notification.
  • context_all — opens the context menu for all the notifications.
  • ignore_dbusclose (default: false) — ignore the dbus CloseNotification message. This is genuinely useful when you want to enforce the timeout that dunst itself configured. Without this parameter, an application can close the notification it sent before your user-defined timeout even hits. Rude, honestly. 🙈
  • override_pause_level (values: [0-100], default: 0) — a notification will pop up whenever the notification's override_pause_level is greater than the paused level. Setting this to anything other than 0 lets you build partial pause modes — the urgent stuff still gets through, the less urgent stuff stays paused. 💖

For example, you can set a low battery notification's override_pause_level to 60 and then set dunst's pause level to 60. That makes dunst show only the battery level notification (and any other notification with override_pause_level >= 60), while everything else stays suspended. 🌸

⌨️ Keyboard shortcuts (X11 only) ⌨️

Keyboard shortcuts get defined like this: "Modifier+key" — where the modifier is one of ctrl, mod1, mod2, mod3, mod4, and key is any keyboard key.

Heads up bestie: the keyboard shortcuts have been moved to the global section of the config, for consistency with the other settings. Don't go looking for them where they used to be. 💀

Alternatively you can define shortcuts inside your window manager and just bind them to dunstctl(1) commands. Whatever vibes with you.

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

  • close — the keyboard shortcut for closing a notification.
  • close_all — the keyboard shortcut for closing all currently displayed notifications.
  • history — the keyboard shortcut for recalling a single notification from history.
  • context — the keyboard shortcut that opens the context menu.

🌈 Urgency sections 🌈

The urgency sections work kinda like rules, and you use them to set 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. That's the whole menu, no substitutions. 🍓

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 versions of dunst let you change the colors of different urgencies through command line options. That's been long removed in favour of RULES, see issue #328. rip to a real one 😭

🧪 Experimental section 🧪

  • per_monitor_dpi (default: false) — use a different DPI for each monitor. This setting is currently implemented only for X11.
  • pause_on_mouse_over (default: false) — pause the notification timeout when you hover with the mouse pointer. This setting is currently implemented only for Wayland. 🦋
  • enable_pcre_regex (default: false) — use PCRE regular expressions for filtering rules. For more info see https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions. This setting overrides enable_posix_regex. 💅

👑 DUNSTCTL 👑

Dunst now ships with a command line control command you can use to interact with it. It supports every function that used to be keyboard-shortcuts-only, but it also has a whole bunch of extra functionality on top. For more info, see dunstctl(1). main character energy fr fr.

🕰️ HISTORY 🕰️

Dunst saves a number of notifications (specified by history_length) in memory. You can recall them (aka redisplay them) by calling dunstctl history (see dunstctl(1)). Whether those notifications will time out like they'd just been sent depends on the value of the sticky_history setting. 🌸

Heads up: actions get invalidated once the notification is closed, so you cannot execute that action when you bring a notification back from history. it's giving expired coupon 😭

Past notifications get redisplayed in a first-in-last-out order — meaning pressing the history key once brings up the most recent notification that had been closed or timed out. 💖

🌊 WAYLAND 🌊

Dunst has had Wayland support since version 1.6.0. Because the Wayland protocol is way more focused on security, some things that are possible in X11 just aren't possible in Wayland. Those differences are reflected in the configuration. The main thing that changes: dunst on Wayland cannot use global hotkeys, so use dunstctl instead. periodt.

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. It's not being shady, it's just honest. 🫶

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 meantime, you can try whether 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 your notifications appear a bit higher or lower than on X11. That's because the notification cannot be placed on top of your status bar. The notifications get placed relative to your status bar, which makes them appear higher or lower by the height of your status bar. We cannot do anything about that behavior. it is what it is 💀

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. no name, no class, just vibes. 🦋

📜 RULES 📜

Rules allow the conditional modification of notifications. They can live in a section with any name — even the special sections. The special sections do not allow filters to be added, since they've got implied filters by default. 🌈

  • 'global' — no filters, matches all notifications. everything, all of it, the whole timeline.
  • 'urgency_low', 'urgency_normal' and 'urgency_critical' — matches low, normal or critical urgency respectively.

There are 2 parts to 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. It's also totally possible to not specify any filters at all, in which case the rule will match all notifications. easy mode 🎀

Rules are applied in order of appearance. Beware: if a notification is changed by a rule, it may affect whether it gets matched by a later rule. so the order is not a suggestion bestie 😭

🔍 filtering

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

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. Eventually enable_posix_regex will be enabled by default. ✨

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). everyone has to agree or nobody goes anywhere.

An example of a 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. fr, save yourself the headache. 🙈
  • "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. two different icons, don't mix them up 💅
  • "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's named that way so it doesn't conflict with trying to modify the urgency. smart tbh 🧠
  • "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, just like 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.

okay so you can also set extra color values (as a comma-separated list, bestie 💅) to define a linear gradient spanning all the length of the progress bar. it's giving rainbow, lowkey.

  • "format" — literally equivalent to the "format" setting. same energy, no notes ✨
  • "frame_color" — the frame color of the notification. peep the COLORS section for the possible values you can put here 🎀
  • "fullscreen" (values: delay/show/pushback/suppress, default: show) — this one says how notifications get handled when a fullscreen window is focused. default is show, so notifications just... get shown. periodt.

The other possible values:

  • delay — notifications already on screen keep being displayed until they're dismissed or time out, but new ones get held back and only shown once the focus to the fullscreen window is lost.
  • pushback — equivalent to delay, except that already existing notifications get paused and hidden until the focus to the fullscreen window is lost.
  • suppress — existing notifications get closed when entering fullscreen and new notifications go straight to history. it's like pushback but without the redisplaying after leaving fullscreen mode.

Wayland tea 🦋: if follow is set to mouse or keyboard, dunst can't figure out which output the notification is on. so dunst will delay or pushback if any of the outputs is fullscreen. and because the fullscreen protocol is fairly new, you'll need a recent version of a compositor that supports it — at the time of writing, you need the git version of sway. also see layer to change whether notifications appear above fullscreen windows in Wayland.

  • "min_icon_size" (default: 32) — the minimum size in pixels for icons. if the icon is larger than or equal to the value you set, it won't be touched at all. if it's smaller, it gets scaled up so that the smaller axis equals the size you specified.

when you're using recursive icon lookup (see enable_recursive_icon_lookup), all icons from a theme will be this size. all of them. every single one.

if icon_position is set to off, this setting is ignored 💀

  • "max_icon_size" (default: 128) — the maximum size in pixels for icons. icon smaller than or equal → untouched, no notes. bigger → scaled down so that the larger axis equals the size you specified.

set it to 0 to disable icon downscaling entirely.

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

  • "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) — where the icon sits in the notification window. setting it to off disables icons.
  • "default_icon" — sets the default icon of the notification; 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 replace each-other, so only the newest one is visible. super useful for like volume or brightness notifications where you only want one of the same type visible, iykyk 🍓

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 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 the 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 😭
  • "override_pause_level" — see override_pause_level.
  • "skip_display" — setting this to true prevents the notification from being displayed initially, but it still gets saved in history for later viewing 🙈
  • "history_ignore" — setting this to true displays the notification initially, but stops it from being recalled via the history.
  • "action_name" (default: "default") — sets the name of the action to be invoked on do_action. if you don't specify it, the action set as default action or the only available action gets 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 true, long lines get 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 gets 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 skips 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 is enough info, like 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:
<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.

  • 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. bestie, automation slay 💜

when the script is called, details of the notification that triggered it get 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, and DUNST_DESKTOP_ENTRY.

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, so to use it the entire value needs to be quoted. for example:
separator_color="#123456"

💅 NOTIFY-SEND HINTS 🎀

okay so this is the fun part: Dunst can pull different colors for a message straight from notify-send ✨. To do that you just have to add a hint with the -h option. And the progress value can be set with a hint too, no cap.

💡 Note: Dunstify is compatible with notify-send and all of these settings work the same way. same energy, different binary, iykyk.

All the accepted hints are listed below, and yes we're listing every single one bestie 🌸

See RULES for more detailed explanations for some options.

  • fgcolor (type: string) — the Foreground color. literally the text color, slay 💅
  • bgcolor (type: string) — the Background color.
  • frcolor (type: string) — the Frame color. it's giving border moment.
  • hlcolor (type: string or string array) — the Highlight color.
  • value (type: int or uint) — the Progress value. this is the one that makes your progress bar go brrr 🔥
  • 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. (so yes, they can never stack, it's a one-in-one-out situation bestie 😭)
  • x-canonical-private-synchronous (type: string) — Alias for x-dunst-stack-tag.

Some examples, copy these fr fr:

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. main character behavior honestly 👑

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. (so like... you can poke them, you just won't know which ones are pokeable 🙈)

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. no dmenu, no menu, periodt.

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. (yes bestie, it just assumes seconds, iconic of it honestly)

Time units understood by dunst are "ms", "s", "m", "h" and "d". ✨

Example time: "1000ms", "10m".

🐛 REPORTING BUGS 💀

Bugs and suggestions should be reported on GitHub at https://github.com/dunst-project/dunst/issues. found a bug? tell the maintainers, they're nice, we don't do mean comments here 🫶

Copyright 2011-2014 Sascha Kruse

Copyright 2014-2026 Dunst contributors

Dunst is released under the BSD 3-Clause License, see LICENSE for more information.

If you feel that copyrights are violated, please send an email to the maintainers.

👀 SEE ALSO 🌈

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

and that's the whole page bestie, you made it to the end 🎉 this was dunst(5), version 1.13.2, dated 2026-03-19 💖 now go forth and notify responsibly, mwah 💅✨

📦 where this page comes from