Waybar Config: Customizing Linux Status Bar

Alaric Bird

4 weeks ago

Share on Social Media

Learn how to configure and customize Waybar on Linux with this complete guide. Optimize your status bar with modules, themes, scripts, and more! #centlinux #linux #waybar

1. Introduction to Waybar

Waybar is a highly customizable status bar designed for Wayland-based window managers like Sway, Hyprland, and River. Unlike traditional Xorg-based status bars like i3bar or Polybar, Waybar offers a modern, efficient, and minimalistic approach for users who prefer a sleek and tailored desktop experience.

Why Use Waybar Over Other Status Bars?

Waybar stands out due to:

Customization – Supports JSON and CSS-based styling.
Performance – Lightweight and fast, ideal for low-resource setups.
Wayland Compatibility – Works seamlessly with Wayland window managers.
Extensive Module Support – Displays system information, workspaces, music player details, and custom scripts.

If you’re using a Wayland-based system and need a feature-rich status bar, Waybar is the best choice.

Waybar Config: Customizing Linux Status Bar

2. Installing Waybar on Linux

Waybar is available in most Linux distributions. The installation process differs based on your package manager.

Installing Waybar on Arch Linux

On Arch-based systems (including Manjaro), install Waybar using:

sudo pacman -S waybar

Installing Waybar on Debian/Ubuntu

For Debian-based distributions, use:

sudo apt install waybar

Installing Waybar on Fedora

Fedora users can install it via:

sudo dnf install waybar

Dependencies Required for Waybar

Waybar relies on various dependencies like:

jq – For processing JSON-based configurations.
pango – For rendering text.
cairo – For graphical rendering.
libinput – For touchpad and mouse input support.

To ensure all dependencies are installed, refer to your package manager’s documentation.

Recommended Training: Complete Linux Training Course to Get Your Dream IT Job 2025 from Imran Afzal

3. Understanding the Waybar Configuration

Waybar is configured using JSON for defining modules and CSS for styling.

JSON and CSS Configuration Files

~/.config/waybar/config – Defines modules, positioning, and behavior.
~/.config/waybar/style.css – Controls the visual appearance.

Default Configuration File Location

If you haven’t created a custom configuration, Waybar uses a default setup. To customize, copy the default config:

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

Structure of the JSON Configuration File

A basic JSON config looks like this:

{
    "layer": "top",
    "modules-left": ["sway/workspaces", "sway/mode"],
    "modules-center": ["clock"],
    "modules-right": ["network", "battery"]
}

This setup:

Places workspaces on the left.
Displays the clock in the center.
Shows network and battery status on the right.

4. Basic Waybar Configuration

Editing the Configuration File

To modify the Waybar settings, open the configuration file in your preferred editor:

nano ~/.config/waybar/config

Make changes and restart Waybar to apply them:

pkill waybar && waybar &

Modifying Default Modules

Waybar includes several default modules like:

clock – Shows the current date and time.
battery – Displays battery percentage.
network – Indicates Wi-Fi or Ethernet connection.
sway/workspaces – Shows active workspaces in Sway.

To remove a module, delete its entry from the "modules-left", "modules-center", or "modules-right" arrays.

Adding Custom Modules

To add a custom module, modify the JSON config:

"custom/uptime": {
    "exec": "uptime -p",
    "interval": 30
}

This adds a custom uptime display that updates every 30 seconds.

5. Customizing Waybar Appearance

Editing the CSS File

Waybar’s appearance is controlled via CSS. Open the file for editing:

nano ~/.config/waybar/style.css

Changing Font, Colors, and Spacing

Example CSS snippet to change colors and font:

* {
    font-family: "JetBrainsMono Nerd Font";
    font-size: 12px;
    color: #ffffff;
}

#waybar {
    background: #282c34;
    border-bottom: 2px solid #61afef;
}

This applies:

JetBrainsMono Nerd Font for text.
White text (#ffffff).
Dark background (#282c34).
Blue bottom border (#61afef).

Using Icons for a Better Look

Icons can enhance your Waybar experience. Install FontAwesome or Nerd Fonts:

sudo apt install fonts-font-awesome

Then modify your JSON config to include an icon:

"clock": {
    "format": " {:%H:%M}"}

This adds a clock icon before the time.

6. Waybar Modules and Their Customization

Waybar offers a variety of built-in modules that you can configure and customize to fit your needs. Some of the most commonly used modules include:

Available Built-in Modules

Here are some essential modules you can use in your Waybar configuration:

clock – Displays the current date and time.
battery – Shows battery percentage and charging status.
network – Indicates Wi-Fi or Ethernet status.
cpu – Displays CPU usage percentage.
memory – Shows RAM usage.
disk – Monitors disk space.
temperature – Displays CPU/GPU temperature.
pulseaudio – Controls volume and shows current level.
backlight – Adjusts screen brightness.
bluetooth – Displays Bluetooth connection status.
custom – Allows you to add custom scripts.

Configuring System Information Modules

To monitor CPU, memory, and disk usage, update your config file:

"cpu": {
    "format": " {usage}%"
},
"memory": {
    "format": " {used}MB/{total}MB"
},
"disk": {
    "path": "/",
    "format": " {used}/{total}GB"
}

These settings will:

Show CPU usage with an icon.
Display memory usage in MB.
Monitor disk usage for the root directory.

Configuring Network and Bluetooth Status

If you want to monitor your network connection and Bluetooth, add:

"network": {
    "interface": "wlan0",
    "format": "{ifname}: {signalStrength}%"
},
"bluetooth": {
    "format": "{icon} {status}"
}

This will:

Show the current Wi-Fi interface and signal strength.
Display Bluetooth status and connection info.

Configuring Workspaces and Window Titles

For better workspace management, use:

"sway/workspaces": {
    "format": "{icon} {name}"
},
"sway/window": {
    "format": "{title}"
}

Displays workspace names and icons.
Shows the active window’s title.

Adding a Custom Script

You can add custom scripts to display extra information, like weather:

"custom/weather": {
    "exec": "curl -s 'wttr.in/?format=3'",
    "interval": 600
}

This fetches weather updates every 10 minutes.

7. Using Waybar with Different Window Managers

Waybar works with various Wayland-based window managers. Some require extra configuration.

Waybar with Sway

Sway, a popular i3-compatible Wayland compositor, integrates well with Waybar. Add this to your ~/.config/sway/config:

exec waybar

Waybar with Hyprland

For Hyprland users, enable Waybar by adding this to ~/.config/hypr/hyprland.conf:

exec-once = waybar

Waybar with i3

If you’re using Waybar with i3 (Xorg) instead of a Wayland compositor, launch it with:

exec --no-startup-id waybar

8. Enhancing Functionality with Scripts

One of Waybar’s most powerful features is the ability to execute custom scripts.

Writing Custom Bash Scripts

For example, a script to display battery status dynamically:

#!/bin/bash
battery_level=$(cat /sys/class/power_supply/BAT0/capacity)
echo "Battery: $battery_level%"

Save it as ~/.config/waybar/battery.sh and make it executable:

chmod +x ~/.config/waybar/battery.sh

Add it to your config file:

"custom/battery": {
    "exec": "~/.config/waybar/battery.sh",
    "interval": 30
}

This updates battery status every 30 seconds.

Using Python Scripts for Dynamic Updates

You can also use Python for more complex tasks. Here’s an example for displaying CPU temperature:

#!/usr/bin/env python3
import psutil
print(f"CPU Temp: {psutil.sensors_temperatures()['coretemp'][0].current}°C")

Add it as a Waybar module similarly to Bash scripts.

Scheduling Updates for Scripts

To optimize performance, you can run scripts at intervals instead of constantly executing them.

9. Improving User Experience with Icons and Fonts

Icons and fonts significantly improve readability and appearance.

Installing and Using FontAwesome Icons

Waybar supports FontAwesome and Nerd Fonts for displaying icons. Install them using:

sudo apt install fonts-font-awesome

Using Nerd Fonts for Additional Icons

Nerd Fonts provide even more icons. Download and install a Nerd Font like JetBrainsMono:

wget https://github.com/ryanoasis/nerd-fonts/releases/latest/download/JetBrainsMono.zip
unzip JetBrainsMono.zip -d ~/.local/share/fonts
fc-cache -fv

Adjusting Icon Sizes and Alignment

Modify the CSS file to adjust the size and spacing:

#clock {
    font-size: 14px;
    padding: 5px;
}

10. Advanced Configuration Techniques

For those who want even more control, here are some advanced techniques.

Using Multiple Waybar Instances

Run multiple instances of Waybar by creating separate configs:

waybar -c ~/.config/waybar/config2.json -s ~/.config/waybar/style2.css

Conditional Styling Based on Events

Waybar supports dynamic CSS changes. Example: change color when battery is low:

@keyframes blink {
    50% {
        color: red;
    }
}

#battery.warning {
    animation: blink 1s infinite;
}

Debugging and Troubleshooting Configuration Issues

To debug, run:

WAYBAR_LOG_LEVEL=debug waybar

This prints detailed logs for troubleshooting.

11. Waybar Keybindings and Interactivity

You can add interactivity using click, scroll, and hover events.

Making Waybar Clickable

To run a command when clicking the clock:

"clock": {
    "format": " {:%H:%M}",
    "on-click": "gnome-calendar"
}

Using Actions for Click Events

Other interactive options:

on-scroll-up: Adjusts volume or brightness.
on-click: Opens an app.
on-hover: Displays additional info.

Adding Scroll and Hover Actions

Example for controlling volume:

"pulseaudio": {
    "on-scroll-up": "pactl set-sink-volume @DEFAULT_SINK@ +5%",
    "on-scroll-down": "pactl set-sink-volume @DEFAULT_SINK@ -5%"
}

12. Waybar and Notifications

Integrating notifications into Waybar can improve usability, allowing you to see alerts directly in your status bar.

Integrating Dunst for Notifications

Dunst is a lightweight notification daemon commonly used with Waybar. Install it using:

sudo apt install dunst

Start Dunst by adding this to your startup configuration:

exec --no-startup-id dunst

Displaying Alerts in Waybar

To display notifications in Waybar, use a custom script that fetches the latest notification:

#!/bin/bash
dunstctl history | head -n 1

Save it as ~/.config/waybar/notifications.sh and add it to your Waybar config:

"custom/notifications": {
    "exec": "~/.config/waybar/notifications.sh",
    "interval": 5
}

This script updates every 5 seconds to show the latest notification.

Managing Notification Popups

To customize how long notifications stay visible, edit ~/.config/dunst/dunstrc:

[global]
timeout = 10

This ensures notifications stay visible for 10 seconds before disappearing.

13. Waybar Performance Optimization

Waybar is lightweight, but if you’re running multiple scripts, optimization can prevent slowdowns.

Reducing CPU and Memory Usage

Minimize the number of scripts executed at short intervals.
Use compiled binaries instead of Bash/Python scripts.
Limit updates for modules that don’t need frequent refreshes (e.g., disk usage).

Optimizing Script Execution

Instead of constantly polling system data, use event-driven updates. Example: Instead of running uptime every second, trigger an update only when the system load changes.

Caching and Lazy Loading of Modules

You can cache script outputs to avoid redundant execution. Modify your script to store the last value and update only when it changes.

Saving and Restoring Waybar Configurations

To back up your configuration:

tar -czvf waybar_backup.tar.gz ~/.config/waybar

Restore it using:

tar -xzvf waybar_backup.tar.gz -C ~/

To share your Waybar setup, push your configuration files to a Git repository:

cd ~/.config
git init
git add waybar
git commit -m "My Waybar Config"
git remote add origin <your-repo-url>
git push -u origin main

Read Also: How to install Git on Linux 9

Finding and Using Community-Made Configurations

Many users share their Waybar configs online. Websites like r/unixporn and GitHub are great places to find inspiration.

To use someone else’s configuration, simply clone their repository and copy the files to your Waybar directory:

git clone <repo-url> ~/.config/waybar

15. Conclusion and Final Tips

Waybar is a powerful and customizable status bar for Wayland window managers. With JSON and CSS configurations, you can tailor its appearance and functionality to your liking. Whether you’re displaying system stats, notifications, or custom scripts, Waybar provides endless customization possibilities.

Struggling with AWS or Linux server issues? I specialize in configuration, troubleshooting, and security to keep your systems performing at their best. Check out my Fiverr profile for details.

Common Pitfalls to Avoid

Syntax Errors in JSON – Always validate your config with jq . <config> before restarting Waybar.
Forgetting to Restart Waybar – After making changes, run pkill waybar && waybar &.
High CPU Usage – Reduce the number of frequently updating scripts.

Resources for Further Learning

Frequently Asked Questions (FAQs)

1. How do I restart Waybar after making changes?

You can restart Waybar with:

pkill waybar && waybar &

2. Why is my Waybar not displaying certain modules?

Ensure the module is correctly listed in the config file. Check logs by running:

WAYBAR_LOG_LEVEL=debug waybar

3. Can I use Waybar with X11?

Yes, but it’s optimized for Wayland. It works with i3, but Polybar is often a better choice for X11.

4. How do I change the font in Waybar?

Edit style.css and update the font-family:

* {
    font-family: "JetBrainsMono Nerd Font";
}

5. Where can I find pre-made Waybar configurations?

Check GitHub or r/unixporn for user-shared setups.

Table of Contents