Skip to content
Get packs

Guide · Open source

How to use Waybar: install, configure and style it

Updated · written with AI from the project's own documentation and checked against our catalogue data

Waybar is a free, open-source status bar for Linux desktops running Wayland, the display system that replaces X11. It is built for Sway and other wlroots-based compositors, and it shows items such as workspaces, the clock, battery, network and audio. This guide walks through building Waybar from source, running it, and customizing its config and style files so it looks and behaves the way you want.

WaybarAlexays/Waybar · ★ 12.1k · MIT

Quick start

  1. 1Clone the repository. Run git clone on the Alexays/Waybar GitHub repository and move into the Waybar folder.
  2. 2Install the prerequisites. Install Meson, Ninja, a C++ compiler and the runtime libraries listed in the README for your distribution.
  3. 3Set up the build. Run meson setup build inside the project folder to prepare the build directory.
  4. 4Compile Waybar. Run ninja -C build to compile the project.
  5. 5Launch the bar. Run ./build/waybar to start it without installing, using the default config.
  6. 6Copy and edit the config. Copy the default config and stylesheet into ~/.config/waybar/ and change the modules and styling you want.

Check that Waybar fits your setup

Waybar is a bar for Wayland. The project describes it as a highly customizable bar for Sway and wlroots-based compositors, and its feature table lists support for Sway, River, Hyprland, Niri, Mango, DWL and Wayfire.

It expects you to edit configuration by hand. The default config is a starting point, not a finished bar. If you run X11, or GNOME or KDE, the project's own description points you to a different tool.

  • Good fit: Sway or Hyprland users who want a configurable status bar
  • Good fit: people comfortable editing JSON and CSS-style files
  • Not a fit: X11 users, or people who want a bar that works with no config editing

Install Waybar from source

Most distributions package Waybar, and the README links to a packaging status page. To build it yourself, clone the repository, set up the build with Meson, and compile with Ninja. You need Meson, Ninja, a C++ compiler and the build and runtime libraries listed in the README.

The README lists the dependencies by name, including gtkmm3, jsoncpp, libsigc++, fmt, wayland, spdlog and upower. It also provides separate dependency lists for Ubuntu and Arch, which you can install with your package manager before building.

  • Prerequisites: Meson, Ninja, a C++ compiler, and the libraries in the README's runtime dependencies list
  • Some modules need extra libraries, such as libpulse for the PulseAudio module and libnl for the Network module
git clone https://github.com/Alexays/Waybar cd Waybar meson setup build ninja -C build

Run Waybar without installing it

After the build finishes, you can start the bar straight from the build folder. This is useful for testing before you commit to a setup. Waybar launches with a built-in default config, so you can see it working before you change anything.

The optional install step copies Waybar onto your system. The README marks it as optional, so you can skip it while you are still testing.

./build/waybar ninja -C build install # optional

Create your own config and style files

To customize the bar, copy the default config and stylesheet into ~/.config/waybar/ and edit the copies. The default config lives in the project's resources folder as config.jsonc. Changing the copies leaves the original defaults untouched.

The config file decides which modules appear and where. The stylesheet controls how they look. The project's wiki has separate Configuration and Styling guides that list every option, and an Examples page with community setups you can adapt.

  • Copy resources/config.jsonc to ~/.config/waybar/
  • Copy the default stylesheet to ~/.config/waybar/ alongside it
  • Edit the copies, restart Waybar and check the result

Pick modules for battery, network, audio and more

Modules are the individual items on the bar. The README groups them into power and hardware, connectivity, audio and media, and desktop. Examples include Battery, Network, Bluetooth, PulseAudio, WirePlumber, MPRIS, Clock, System tray and Custom scripts.

Each module has its own page on the project wiki, which is the place to check its options. The Custom module lets you show the output of your own script, which is useful for items the built-in modules do not cover.

  • Power and hardware: Battery, UPower, CPU, Memory, Disk, Temperature
  • Connectivity: Network, Bluetooth, WWAN
  • Audio and media: PulseAudio, WirePlumber, MPD, MPRIS
  • Desktop: Clock and calendar, System tray, Idle inhibitor, Custom scripts

Troubleshoot and find documentation

The README points to the wiki and FAQ for configuration questions. Module documentation is written in the man/ folder in scdoc format and synced to the wiki, so the man pages are the source to check when a wiki page and the code disagree.

If a module does not appear, check that the library it needs was installed before you built Waybar. The optional modules listed in the runtime dependencies section each need a specific library.

  • Read the Configuration and Styling wiki pages for option names
  • Check the FAQ page on the wiki for common problems
  • Only download Waybar from the official GitHub page, since the project has no official website

What people use it for

  • Show workspaces, clock and battery on a laptop running Sway
  • Display network and audio status on a Hyprland desktop
  • Add a custom script output to the bar with the Custom module
  • Show media playback from MPRIS or MPD on the bar

Frequently asked questions

Is Waybar free?

Yes. Waybar is licensed under the MIT license, and the LICENSE file in the repository has the full terms. The README also includes a donation link, but donating is not required to use it.

Does Waybar work on X11?

No. The README describes Waybar as a Wayland bar for Sway and wlroots-based compositors. X11 users should look for a bar built for their setup.

How do I install Waybar?

Most distributions package it, so check your package manager first. To build from source, clone the GitHub repository, run meson setup build, then ninja -C build, as shown in the README.

What do I need to build Waybar?

You need Meson, Ninja, a C++ compiler and the build and runtime libraries listed in the README, including gtkmm3, jsoncpp, libsigc++, fmt, wayland and spdlog.

Where is the Waybar config file?

Copy the default config from the project's resources folder into ~/.config/waybar/ and edit it there. The project's Configuration and Styling wiki pages explain the options.

How does Waybar compare to Polybar or eww?

Polybar is an X11 bar and eww is a general widget tool, so they serve different setups. Waybar targets Wayland compositors such as Sway, and the README does not compare it directly to these tools, so check each project's docs for details.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Waybar suits Wayland users on Sway, Hyprland or another wlroots-based compositor who are happy to edit JSON and CSS-style config files to build their own bar. If you use X11, GNOME or KDE, or want a bar that works without manual setup, pick a different tool.

Install options & downloads