From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

Waybar is a status bar for Wayland compositors.


USE flags

USE flags for gui-apps/waybar Highly customizable Wayland bar for Sway and Wlroots based compositors

evdev Enable libevdev support for evdev related features
experimental Enable experimental features, such as Bluetooth battery reporting
jack Add support for the JACK Audio Connection Kit
libinput Enable libinput support for libinput related features
logind Enable support for logind (bluetooth and idle inhibit)
mpd Enable support for the Music Player Daemon
mpris Enable support for mpris
network Enable libnl support for network related features
pipewire Enable support for pipewire
popups Enable popup support with gtk-layer-shell
pulseaudio Enable support for volume control via PulseAudio
sndio Enable support for volume control via sndio
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
tray Enable support for tray
udev Enable virtual/udev integration (device discovery, power and storage device support, etc)
upower Enable power management support
wifi Enable support for wifi/rfkill


root #emerge --ask gui-apps/waybar


To view all available configuration options:

user $man 5 waybar


Example config and style.css files are provided in the /etc/xdg/waybar/ directory:

user $mkdir -p ~/.config/waybar/
user $cp /etc/xdg/waybar/config ~/.config/waybar/
user $cp /etc/xdg/waybar/style.css ~/.config/waybar/


Waybar supports three main ways to set color for particular element: rgb e.g: rgb(100, 114, 125), rgba e.g: rgba(100, 114, 125, 0.5) and css styled colors e.g: #red or #cec2eb.


The main waybar window can be styled with the following:

       <name> is set to the value of the optional name configuration property. If not set, this class is not available. 
       <position> is set to the value of the position configuration property.

A style with the .module selector would affect all the modules. In practice, you may prefer to use more specific label.module and box.module selectors.

FILE ~/.config/waybar/style.cssExample on styling
label.module {
    padding: 0 10px;
    box-shadow: inset 0 -3px;
    background-color: rgba(100, 114, 125, 0.5);
box.module button:hover {
    box-shadow: inset 0 -3px #ffffff;
    background-color: rgba(100, 114, 125, 0.8);


To utilise Font Awesome icons, install the media-fonts/fontawesome package.

The simplest way to use the icons is to set the font-family property in style.css, specifying "Font Awesome 6 Free" after the preferred font for text, e.g.:

FILE ~/.config/waybar/style.cssAdd support for Font Awesome icons
* {
    font-family: "Gentium Plus", "Font Awesome 6 Free", serif;

However, this will not always result in the desired behaviour for all Waybar modules. In particular, it will result in icons not displaying properly in some modules: the icons can be made to display by reversing the order of values of the font-family property for a module, but that will result in Font Awesome being used for non-icon text as well.

An approach to address these issues via fontconfig was described in this comment on the relevant Waybar issue. Firstly, if ~/.config/fontconfig/fonts.conf does not already exist, create it with the following contents:

FILE ~/.config/fontconfig/fonts.confAdd support for Font Awesome icons
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
      <family>Font Awesome 6 Free</family>

Otherwise, add the above alias element subtree within the fontconfig element in the existing file.

Then, each icon in the config file should be wrapped in span font='icon' tags, e.g.:

"format": "<span font='icon'></span> {usage:2}%"


"format": "<span font='icon'>{icon}</span> {capacity}%"

Finally, the font-family property in style.css should be set to only the font(s) for non-icon text, e.g.:

* {
    font-family: "Gentium Plus";

After restarting Waybar, both icons and non-icon text should now be displayed appropriately.

Applying configuration changes

Modifications to the style.css file, once saved, can be applied by sending the Waybar process a SIGUSR2 signal, e.g. pkill -SIGUSR2 waybar. However, modifications to the config file can only be applied by restarting the Waybar process. A script like below could be used to restart Waybar:

FILE launch-waybar.shRestart waybar when config changed.
CONFIG_FILES="$HOME/.config/waybar/config $HOME/.config/waybar/style.css"
trap "killall waybar" EXIT
while true; do
    waybar &
    inotifywait -e create,modify $CONFIG_FILES
    killall waybar

See also