mako(5)

📦
version 1.11.0 · 13 versions
, in arch rolling, ubuntu stonking

💖 NAME 💖

mako(5) — File Formats Manual — the configuration file, bestie. This is the page that tells you how to make your mako config pop off. ✨

🎀 DESCRIPTION 🎀

Okay so the config file lives at ~/.config/mako/config or at $XDG_CONFIG_HOME/mako/config. Option lines are literally just:

key=value

Empty lines and lines that begin with # are ignored. No cap, that’s the whole vibe check. 🫶

✨ GLOBAL CONFIGURATION OPTIONS ✨

These are the big-picture settings that run the whole show. 🌈

  • max-history=n — Set the maximum number of expired notifications to keep in the history buffer to n. If the buffer is full, newly expired notifications replace the oldest ones. If 0, history is disabled.

Default: 5

  • sort=+/-time | +/-priority — Sorts incoming notifications by time and/or priority in ascending (+) or descending (-) order.

Default: -time

  • include=config path — Includes a config at the specified path. The path must be absolute or otherwise start with ~/. iykyk 💜

Default: none

🦋 BINDING OPTIONS 🦋

Bindings are the “when this event happens, do this action” girlies. One event, one action, main character energy. 💅

🫶 Supported options 🫶

  • on-button-left=action — Performs the action when the left pointer button is pressed.

Default: invoke-default-action

  • on-button-middle=action — Performs the action when the middle pointer button is pressed.

Default: none

  • on-button-right=action — Performs the action when the right pointer button is pressed.

Default: dismiss

  • on-touch=action — Performs the action when tapped via a touch device.

Default: dismiss

  • on-notify=action — Performs the action when the notification is opened.

Default: none

🌈 Supported actions 🌈

  • none — Do nothing. Sometimes that’s the vibe. 🦋
  • dismiss [--no-history] — Dismiss the current notification. If --no-history is passed, the notification won’t be added to history. Periodt.
  • dismiss-all — Dismiss all notifications. 💀
  • dismiss-group — Dismiss notifications in the current group.
  • invoke-action <action> — Invoke the named action on the notification.

An xdg-activation token will be sent to the client, allowing the client to request focus from the compositor. The compositor must support the xdg_activation_v1 protocol and allow the focus request for the following example to work correctly:

[app-name="some-app-id" actionable]
on-button-left=invoke-action mail-reply-sender
  • invoke-default-action — Invoke the default action on the notification. ✨
  • exec <command> — Execute a shell command.

The command will be executed in a POSIX shell. The shell variable id will be set to the notification ID. For example, the following option will display an interactive action menu on middle click:

on-button-middle=exec makoctl menu -n "$id" -- wmenu -p 'Select action: '

The following option will play a sound when a new notification is opened:

on-notify=exec mpv /usr/share/sounds/freedesktop/stereo/message.oga

💅 STYLE OPTIONS 💅

This is the visual glow-up section. The way that a config can change the whole notification aesthetic? Obsessed. 🌈✨

Default: monospace 10

  • background-color=color — Set background color to color. See COLORS for more information.

Default: #285577FF

  • text-color=color — Set text color to color. See COLORS for more information.

Default: #FFFFFFFF

  • width=px — Set width of notification popups.

Default: 300

  • height=px — Set maximum height of notification popups. Notifications whose text takes up less space are shrunk to fit.

Default: 100

  • outer-margin=directional — Set outer-margin of each edge to the size specified by directional. See DIRECTIONAL VALUES for more information. This margin applies to the outside of the whole notification list.

Default: 0

  • margin=directional — Set margin of each edge to the size specified by directional. See DIRECTIONAL VALUES for more information. This margin applies to each individual notification. Note that it applies in addition to outer-margin, meaning first and last notifications will use the sum of both margins. Math but make it cute. 🎀

Default: 10

  • padding=directional — Set padding on each side to the size specified by directional. See DIRECTIONAL VALUES for more information.

Default: 5

  • border-size=px — Set popup border size to px pixels.

Default: 2

  • border-color=color — Set popup border color to color. See COLORS for more information.

Default: #4C7899FF

  • border-radius=directional — Set popup corner radius on each side to the size specified by directional. See DIRECTIONAL VALUES for more information. Rounded corners are literally iconic. 💚

Default: 0

  • progress-color=[over|source] color — Set popup progress indicator color to color. See COLOR for more information. To draw the progress indicator on top of the background color, use the over attribute. To replace the background color, use the source attribute (this can be useful when the notification is semi-transparent).

Progress can be indicated in a notification by setting a hint, "value" to an integer between 0 and 100 inclusive.

Default: over #5588AAFF

  • icons=0|1 — Show icons in notifications. 🖼️

Default: 1

  • max-icon-size=px — Set maximum icon size to px pixels.

Default: 64

  • icon-path=path[:path...] — Paths to search for icons when a notification specifies a name instead of a full path. Colon-delimited. This approximates the search algorithm used by the XDG Icon Theme Specification, but does not support any of the theme metadata. Therefore, if you want to search parent themes, you’ll need to add them to the path manually.

The path should be the root of the icon theme, the categories and resolutions will be searched for the most appropriate match.

/usr/share/icons/hicolor and /usr/share/pixmaps are always searched. Always. Searching. Periodt.

Default: ""

  • icon-location=position — Position of the icon relative to the displayed text. Valid options are left, right, top and bottom.

Default: left

  • icon-border-radius=px — Sets icon corner radius to px pixels.

Default: 0

  • markup=0|1 — If 1, enable Pango markup. If 0, disable Pango markup. If enabled, Pango markup will be interpreted in your format specifier and in the body of notifications.

Default: 1

  • actions=0|1 — Applications may request an action to be associated with activating a notification. Disabling this will cause mako to ignore these requests.

Default: 1

  • history=0|1 — If set, mako will save notifications that have reached their timeout into the history buffer instead of immediately deleting them. max-history determines the size of the history buffer.

Default: 1

  • format=format — Set notification format string to format. See FORMAT SPECIFIERS for more information. To change this for grouped notifications, set it within a grouped criteria. Format girlies, rise. 💜

Default: <b>%s</b>\n%b Default when grouped: (%g) <b>%s</b>\n%b

  • text-alignment=left|center|right — Set notification text alignment.

Default: left

  • default-timeout=timeout — Set the default timeout to timeout in milliseconds. To disable the timeout, set it to zero.

Default: 0

  • ignore-timeout=0|1 — If set, mako will ignore the expire timeout sent by notifications and use the one provided by default-timeout instead.

Default: 0

  • group-by=field[,field,...] — A comma-separated list of criteria fields that will be compared to other visible notifications to determine if this one should form a group with them. All listed criteria must be exactly equal for two notifications to group. Group chat rules, but for notifications. 💅

Default: none

  • max-visible=n — Set maximum number of visible notifications to n. Older notifications will be hidden. If -1, all notifications are visible.

Default: 5

  • output=name — Show notifications on the specified output. If empty, notifications will appear on the focused output.

Requires the compositor to support the Wayland protocol xdg-output-unstable-v1 version 2.

Default: ""

  • layer=layer — Arrange mako at the specified layer, relative to normal windows. Supported values are background, bottom, top, and overlay. Using overlay will cause notifications to be displayed above fullscreen windows, though this may also occur at top depending on your compositor.

Default: top

  • anchor=position — Show notifications at the specified position on the output. Supported values are top-right, top-center, top-left, bottom-right, bottom-center, bottom-left, center-right, center-left and center. Pick your placement era. ⭐

Default: top-right

✨ CRITERIA ✨

okay bestie so besides all the options at the top of the file, your config can also have zero or more sections 💅 and each one can hold any combo of the BINDING OPTIONS and STYLE OPTIONS. These sections? They're called criteria and you define them with that INI-ish square bracket syntax. The brackets can hold any number of fields, like this:

[field=value field2=value2 ...]

So when a notification comes in, it gets compared against the fields defined in each criteria. If all the fields match — boom, the style options inside get applied to that notification 🎀. Fields you didn't include in the criteria just don't get considered during the match, no big deal. And a notification can match any number of criteria. This matching happens in the order the criteria appear in your config file, which means if multiple criteria match a notification, the last occurrence of any given style option "wins" 👑.

These are the fields available in criteria:

  • app-name (string)
  • app-icon (string)
  • summary (string): exact match on the summary of the notification. Ngl this field conflicts with summary~.
  • summary~ (string): a POSIX extended regular expression match on the summary of the notification. Also conflicts with summary.
  • body (string): exact match on the body of the notification. Conflicts with body~.
  • body~ (string): a POSIX extended regular expression match on the body of the notification. Conflicts with body.
  • urgency (one of "low", "normal", "critical")
  • category (string)
  • desktop-entry (string)
  • actionable (boolean)
  • expiring (boolean)
  • mode (string): only applies the style options in this section if the provided mode is currently enabled. Wanna know more about modes? Scroll to the MODES section 🫶

There's also a second set of fields for a second pass — these match based on where your previous style options decided to place each notification:

  • grouped (boolean): whether the notification is grouped with any others.
  • group-index (int): the notification's index within its group, or -1 if it's not grouped.
  • hidden (boolean): special field that defines the style for the placeholder shown when the number of notifications or groups exceeds max-visible.
  • output (string): which output the notification was sorted onto. Peep the output style option for possible values.
  • anchor (string): which position on the output the notification was assigned to. Check the anchor style option for possible values.
Heads up 🙈 only two passes get performed on each notification, so second-pass criteria are not allowed to reposition the notification.

If a field's value has special characters in it, you can escape them with a backslash, or just quote it:

[app-name="Google Chrome"]

[app-name=Google\ Chrome]

Quotes inside quotes can be escaped too, and a literal backslash is written as \\. No spaces allowed around the equal sign, periodt. Oh and escaping equal signs inside values? Unnecessary, don't bother ✨.

Also booleans can be written any of true/false, 0/1, or as bare words:

[actionable=true] [actionable=1] [actionable]

[actionable=false] [actionable=0] [!actionable]

There are three criteria that are always chilling at the front of the list:

  • An empty criteria that matches all notifications and holds the defaults for all style options, overwritten with whatever you configured in the global section.
  • [grouped], which sets the default format for grouped notifications and sets them invisible.
  • [group-index=0], which makes the first member of each group visible again.

You can override these options by simply defining the criteria yourself and overriding them, easy 💅.

And there are some rules about what you're allowed to configure depending on what a given criteria is matching. Criteria matching grouped or group-index are not allowed to change the anchor, output, or group-by, because that would invalidate the grouping 😭. Also grouping only happens once, not recursively, specifically to avoid the potential for infinite loops. We stay safe out here.

✨ CRITERIA-ONLY STYLE OPTIONS ✨

Some style options just aren't useful in the global context, so they don't have an associated command-line option. It's giving exclusive 🎀

  • invisible=0|1 — whether this notification should be invisible even if it's above the max-visible cutoff. This is used primarily for hiding members of groups. If you want to make more than the first group member visible, turn this option off inside a group-index criteria.

Default: 0

🌈 COLORS 🌈

Colors can be specified as #RRGGBB or #RRGGBBAA — literally that simple, no cap 💖

🦋 DIRECTIONAL VALUES 🦋

Some options set values that affect all four edges of a notification. You can specify these in several different ways depending on how much control over each edge you actually want, iykyk:

  • A single value will apply to all four edges.
  • Two values will set vertical and horizontal edges separately.
  • Three will set top, horizontal, and bottom edges separately.
  • Four will set top, right, bottom, and left edges separately.

When you're specifying multiple values, comma-separate them, bestie. For example, this would set the top margin to 10, left and right to 20, and bottom to five:

margin = 10,20,5

⭐ FORMAT SPECIFIERS ⭐

Format specification works similarly to printf(3), but with a different set of specifiers 👑

  • %% — Literal "%"
  • \\ — Literal ""
  • \n — New Line

For notifications

  • %a — Application name
  • %s — Notification summary
  • %b — Notification body
  • %g — Number of notifications in the current group
  • %i — Notification id

For the hidden notifications placeholder

  • %h — Number of hidden notifications
  • %t — Total number of notifications

💜 MODES 💜

mako supports applying style options conditionally via modes, and honestly? iconic. A configuration section with a mode criteria will only be applied if the current mode matches. You can use makoctl(1) to change the current mode 💅

The initial list of modes contains a single mode called "default". This is deprecated — in a future version the initial list of modes will be empty. Consider yourself warned 🫶

So for example, to hide all notifications when the mode do-not-disturb is enabled:

[mode=do-not-disturb]
invisible=1

Then makoctl mode -a do-not-disturb will hide all notifications, and makoctl mode -r do-not-disturb will show them again. Slay ✨

🌸 AUTHORS 🌸

Maintained by Simon Ser <contact@emersion.fr>, who is assisted by other open-source contributors. For more information about mako development, see https://github.com/emersion/mako. Genuinely so grateful to the maintainers fr fr 🫶

🎀 SEE ALSO 🎀

mako(1) makoctl(1)

okay that's the whole page, bestie, you're officially a mako expert 💖 This was mako(5), dated 2026-03-26 — go forth and style your notifications, you absolute main character 🌈👑✨

📦 where this page comes from