Waybar: a Wayland status bar configured by JSON and CSS

What Waybar is for, and who ends up using it

A Wayland session has no built-in panel. Sway, Hyprland and the other wlroots compositors draw windows and nothing else, so workspace indicators, a clock, battery state and a system tray have to come from a separate process. Waybar fills that role. It is a GTK bar that runs as a client of the compositor and renders a row of modules, each module a small widget bound to a data source: a D-Bus service, a file in /sys, a pipe from the compositor, or a shell command you write yourself.

The audience is narrow and specific. You need to be running one of the compositors in the integration table, and you need to be comfortable editing text files. There is no settings application. The README points at the wiki for Configuration, Styling and Examples, and the default config ships as resources/config.jsonc. That file is the starting point, not a fallback. If you would rather not write JSON, Waybar is the wrong tool and no amount of module coverage changes that.

The module system and how compositor data reaches it

Waybar's architecture is a fixed set of compiled modules plus one escape hatch. The README groups the built-in modules by domain: power and hardware (Battery, UPower, PowerProfilesDaemon, Backlight, CPU, Memory, Disk, Temperature), connectivity (Network, Bluetooth, GPS, WWAN), audio and media (PulseAudio, WirePlumber, JACK, sndio, Cava, MPD, MPRIS), and desktop (Clock, Tray, Idle Inhibitor, Keyboard State, Privacy, Gamemode, Systemd failed units, Image, Custom scripts). Each module has its own wiki page, and the README states that module documentation is authored in man/ using scdoc and synced to the wiki automatically. That detail matters when you find a wiki page that looks stale: the man page is the source.

The compositor integration is not uniform, and the README's table is the honest place to look. Sway, River, Hyprland, Mango and Wayfire expose workspaces and windows. River and Mango also expose layout. Sway, Hyprland, Niri and Mango expose language. Mode is available on Sway, River, Hyprland, Mango and Wayfire. Niri gives workspaces and language only. DWL gives workspaces and windows, and the README adds a condition: DWL requires the dwl IPC patch. That is the general shape of Waybar's coupling. It reads state through each compositor's own IPC, so a compositor with thin IPC produces a thin bar.

The Custom scripts module is the pressure valve. Anything the built-in modules do not cover can be emitted as text from a command, which is why community configurations stretch Waybar well past its documented feature list. The cost is that you own the polling, the formatting and the failure handling for whatever you add that way.

Installing Waybar and getting a first config running

The README says Waybar is packaged by most distributions and links a Repology packaging table, plus an Ubuntu PPA for more recent versions. If you prefer to build, the repository Makefile wraps the meson steps. This runs the default target, which sets up the build directory and compiles:

make build

You can also follow the README's explicit sequence, which is what the Makefile does under the hood:

meson setup build
ninja -C build
./build/waybar          # run without installing

Running ./build/waybar without installing is the fastest way to see whether the bar starts at all. The README notes that Waybar launches with a sensible default config from resources/config.jsonc. Once it starts, the next step is to copy that config and its stylesheet into ~/.config/waybar/ and edit them there. The repository Makefile also exposes a debug run that raises log verbosity, useful when a module silently renders nothing:

make debug-run

Dependencies are split in the README between runtime and build. The runtime list is the one to read carefully, because it is conditional: libpulse is listed for the Pulseaudio module, libnl for Network, libappindicator-gtk3 and libdbusmenu-gtk3 for Tray, libmpdclient for MPD, libsndio for sndio, and libevdev for KeyboardState. Ubuntu and Arch dependency commands are given in the README as collapsed sections. If a module shows nothing and the binary built cleanly, a missing runtime library from that list is the first thing to check.

Where Waybar stops being the right answer

The configuration is code, and it fails like code. A malformed JSONC file or a module referencing a library that was not present at build time produces a bar that is missing pieces rather than an error dialog. The README does not document a validation command or a schema, so the feedback loop is start the bar, look at it, edit, restart. The repository does carry a test target (meson test -C build --verbose --suite waybar), but that is for the project's own test suite, not for validating your config.

The compositor table is the other hard boundary. If your compositor is not listed, Waybar has no IPC path to its workspace state and you are left approximating with the Custom module. DWL is the sharpest example: the README states the dwl IPC patch is required, which means a stock DWL build cannot feed Waybar workspaces at all. That is not a bug to work around, it is a dependency on a patch maintained outside this project.

There is also a resource question. Waybar is a GTK application with a long dependency list once you enable the audio, network and tray modules. On a minimal system where you only want a clock and a battery percentage, you are still pulling in the GTK stack. The README's own runtime dependency list makes that cost visible before you build.

Waybar against a shell-based bar such as Quickshell

The closest alternative in the same problem space is Quickshell, which the related searches pair with Waybar directly. The difference in approach is where the configuration lives. Waybar gives you a fixed set of compiled C++ modules and a JSONC plus CSS configuration layer on top; you choose modules and set their options. Quickshell is a toolkit for building the shell itself, so the bar is something you write rather than something you configure. That means more code and more control.

The practical consequence for a Waybar user is that anything outside the built-in module list has to go through the Custom scripts module, which returns text and nothing else. If you need a widget with custom interaction, custom drawing or state that does not reduce to a string, Waybar's model runs out before Quickshell's does. Conversely, if your needs map onto the module list, Waybar gets you there with a config file and a stylesheet instead of a codebase. The README's Examples wiki page exists precisely because most people start from someone else's config rather than a blank file.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-20. Releases are infrequent and versioned: 0.15.0 on 2026-02-06, 0.14.0 on 2025-08-08, and 0.13.0 on 2025-06-23. The gap between 0.14.0 and 0.15.0 is roughly six months, which tells you the project ships when it ships rather than on a cadence. For a bar that sits between your compositor and your eyes, that is a reasonable trade: fewer releases to track, but also fewer opportunities for a fix to land.

The upgrade cost is concentrated in your own configuration, not in the binary. Because config lives in ~/.config/waybar/ and is not managed by the package, a distribution upgrade replaces the executable and leaves your files alone. That is convenient until a module option is renamed or removed, at which point the bar starts and one module quietly does nothing. There is no migration tool and the README does not document a deprecation policy for config keys. Checking the man pages in man/ against your config after a version jump is the only reliable method the repository offers.

The licence is MIT, per the LICENSE file and the badge at the top of the README. That is permissive and places few obligations on how you redistribute or modify it, but it also means no warranty. If you are packaging Waybar for others, note the README's caution that distributions are only released on the official GitHub page, which is a statement about where to obtain the code rather than a term of the licence.

Editorial conclusion

Waybar is the right choice if you run Sway, Hyprland, River, Niri, Mango, DWL or Wayfire and you want a bar whose behaviour lives in JSONC files and whose appearance lives in CSS. It is the wrong choice if you want a bar that configures itself through a GUI, or if your compositor is not in the supported table and has no IPC to expose workspace state. Before committing, verify three things: that your compositor appears in the compositor integration table, that the modules you need are present in the wiki module list, and that the runtime dependency for each module you enable is installed on your distribution. DWL users should check the dwl IPC patch requirement first, because Waybar cannot read workspace state without it.

Frequently asked questions

Official sources

1. Alexays/Waybar on GitHub
2. Issues
3. License: MIT
4. README
5. Releases