emersion/mako: a Wayland notification daemon that stays out of your way

What mako solves, and for whom

On Wayland, applications do not draw their own notification popups. They send a message over D-Bus to a notification daemon, and that daemon decides where the popup appears, how long it lives, and what happens when you click it. mako is one of those daemons. The README describes it as "a lightweight notification daemon for Wayland" and notes that it "works on Sway", which is the environment it was clearly written around.

The audience is narrow and specific. If you run a wlroots-based compositor such as Sway, you need something to answer the org.freedesktop.Notifications name on the session bus. Without it, every notify-send call and every application notification goes nowhere. mako fills that slot with a C binary that links against wayland, pango and cairo, and it implements the FreeDesktop Notifications Specification rather than a private protocol. That matters because it means the daemon is not tied to one toolkit: anything that speaks the spec can talk to it.

How the daemon is structured: D-Bus in, Wayland surfaces out

The repository layout tells most of the story. There is a dbus/ directory for the bus interface, protocol/ for generated Wayland protocol code, and a flat set of C files at the top level: notification.c, render.c, surface.c, config.c, criteria.c, mode.c, event-loop.c. That is a small program, and the file names map cleanly onto the pipeline.

A notification arrives over D-Bus and is parsed into a notification object. config.c and criteria.c decide how it should look: mako supports per-notification rules, so the appearance can depend on the application sending it or on the urgency it declares. render.c and surface.c then turn that decision into a Wayland surface drawn with pango and cairo, and pool-buffer.c handles the shared-memory buffers behind it. event-loop.c keeps the whole thing responsive, and main.c wires it together. icon.c is where the optional gdk-pixbuf dependency comes in, since that library is what decodes image data for icons.

The startup model is the part worth understanding before anything else. According to the README, "mako will run automatically when a notification is emitted. This happens via D-Bus activation". The service file fr.emersion.mako.service.in in the repository is what makes that possible. The practical consequence is that mako does not need to be in your compositor's startup sequence at all, and the README frames this as a benefit: it "allows delaying its startup time and speed up system startup".

Building and running mako for the first time

The README lists the dependencies explicitly: meson as a build-time dependency, wayland, pango, cairo, one of systemd, elogind or basu for the sd-bus library, gdk-pixbuf as optional for icons, dbus as a runtime dependency with user-session support, and scdoc as optional for man pages. Install those through your distribution first; the README does not give package manager commands, so the names above are what you search for.

The build itself is three commands, taken verbatim from the README:

meson setup build
ninja -C build
build/mako

After ninja finishes, build/mako is a runnable binary. Running it directly from the build directory is the fastest way to confirm the daemon starts and claims the notification name on your session bus. If it exits immediately, the usual cause is that another notification daemon already owns org.freedesktop.Notifications.

Once it is running, the README points to two manual pages for the real configuration surface: man 5 mako for the configuration file and man makoctl for runtime control. Those pages are generated from the doc/ directory with scdoc, so if you built without scdoc you will not have them installed and should install the package instead. The README also notes that if you have several notification daemons installed you may want to start mako explicitly, and gives the Sway recipe:

exec mako

That line goes in the Sway configuration file. For non-systemd setups the README offers a manual session bus alternative:

dbus-daemon --session --address=unix:path=$XDG_RUNTIME_DIR/bus

For a first real use, the honest answer is that mako has no separate demo mode. You send a notification with whatever tool your system provides and watch the popup appear. The README does not document a test command, so there is nothing here to copy for that step.

Where mako gets thin: documentation and diagnostics

The README is short by design, and it delegates almost everything to man pages and to a wiki FAQ. That is a reasonable choice for a tool this size, but it has consequences. There is no worked configuration example in the README at all. The single most common thing a new user wants, a config file to copy and edit, is not in the repository's front page. You are expected to run man 5 mako and build the file yourself.

The same applies to troubleshooting. If a notification does not appear, the README gives you no diagnostic path. There is no logging flag documented, no debug mode, no way to ask mako why it dropped a message. You are left with the general D-Bus toolkit: check who owns the notification name, check that the daemon is running, check the compositor. That is normal for this class of software, but it is a real cost when something silently fails.

There is also a hard dependency on sd-bus, satisfied by systemd, elogind or basu. On a distribution that ships none of those, or ships them in a way your build cannot find, mako will not compile. The README names the alternatives but does not explain how to select one at build time; meson_options.txt in the repository is where that choice lives, and the README does not describe it. Finally, the runtime dependency on a user session bus is not optional. The README states plainly that user-session support is required, and on a system without it you must start dbus-daemon yourself as shown above.

mako against dunst and SwayNotificationCenter

The obvious comparison is dunst. Both are notification daemons that implement the FreeDesktop spec, both are configured from a text file, and both are commonly paired with tiling compositors. The difference is scope. dunst is a long-running X11-era daemon with a large configuration surface and a history that predates Wayland; mako is Wayland-native from the start, draws through cairo and pango, and leans on D-Bus activation so it does not have to be resident. If your session is X11, mako is not an option at all, since it renders Wayland surfaces. If your session is Wayland and you want the smaller dependency footprint, mako is the more direct fit.

The other comparison is SwayNotificationCenter, which is also Wayland-oriented but takes a different approach: it is a notification center with a persistent history view and a GTK-based interface, so it carries a much heavier toolkit dependency and gives you a browsing UI. mako does not provide that. It shows notifications and lets you act on them through makoctl; there is no history browser in the README's description of the project. Choosing between them is mostly a question of whether you want a center or a daemon.

A third point of comparison is the compositor itself. Some Wayland setups ship their own notification handling, which makes a separate daemon redundant. mako's value is highest where the compositor deliberately leaves notifications to an external process, which is the Sway model the README is written against.

Runtime control, maintenance and licensing

makoctl is the runtime interface. The README says to see man makoctl for it, and the binary is built from makoctl.c at the top level of the repository. This is how you dismiss notifications, and it is the piece that makes mako scriptable from a keybinding. The README does not enumerate makoctl's subcommands, so the man page is the source for those.

On maintenance: the repository is not archived, and the last push was on 2026-06-30. The most recent release listed is v1.11.0 from 2026-03-26, following v1.10.0 in 2025-03-16 and v1.9.0 in 2024-05-12. That is a steady cadence of roughly one release a year, with commits continuing between them. It is a mature, slow-moving project rather than a fast-evolving one, which is what you would expect from a daemon that implements a frozen specification. Upgrade cost is correspondingly low: rebuild, restart, and check whether your configuration file still parses, since the README points to man 5 mako as the authority on the current options rather than promising stability.

The licence is MIT, stated in both the README and the LICENSE file at the repository root. That is permissive: it allows use, modification and redistribution with the copyright notice preserved. It does not impose copyleft obligations on your own code. This is a description of the licence text, not legal advice; if you are redistributing mako in a product, read LICENSE yourself.

Editorial conclusion

Adopt mako if you run Sway or another Wayland compositor and want a notification daemon you can configure from one file and drive from the command line with makoctl. Skip it if you need a cross-platform notifier, a GUI settings panel, or a daemon that documents every runtime knob in the README, because it does not. Before committing, check whether your compositor starts mako itself or needs an exec mako line, confirm which sd-bus provider your distribution ships, and decide whether icons matter enough to pull in gdk-pixbuf.

Frequently asked questions

Official sources

1. emersion/mako on GitHub
2. Issues
3. License: MIT
4. README
5. Releases