Skip to content
Get packs

Guide · Open source

How to use polybar: install, configure and run a Linux status bar

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

Polybar is a free, MIT-licensed tool that draws a status bar along the edge of a Linux desktop. It can show workspaces, the window title, volume, battery, network, CPU and memory load, and the time. This guide walks through installing it, where its configuration fits in, and what to check when it does not behave as expected.

Polybarpolybar/polybar · ★ 15.4k · MIT

Quick start

  1. 1Install polybar. Use your package manager. On Debian or Ubuntu run sudo apt install polybar; on Arch run sudo pacman -S polybar; on Fedora run sudo dnf install polybar.
  2. 2Confirm your window manager. Polybar targets tiling window managers such as i3 and bspwm, and EWMH compliant window managers. Make sure yours is supported.
  3. 3Read the configuration docs. Open the project wiki at github.com/polybar/polybar/wiki to find how to run and configure polybar.
  4. 4Create your settings file. Write a configuration file that defines your bar and the modules you want, such as workspaces, volume, battery and time.
  5. 5Start the bar. Run polybar from your session as described in the wiki and check that the bar appears.
  6. 6Adjust and iterate. Edit the settings file, restart the bar and refine modules until the layout suits you.

What polybar is and who it suits

Polybar is a tool for creating status bars. Its README describes it as a fast and easy-to-use tool, built so you can make a custom bar without needing much shell-scripting skill.

It is aimed at Linux users who run a tiling window manager such as i3 or bspwm, and at people comfortable editing a configuration file. The project's focus is Linux and X11 window managers, so it is a poor fit for macOS or Windows.

  • Good fit: Linux users on i3 or bspwm who want a custom bar
  • Good fit: users who want built-in modules for audio, music player, network and battery
  • Poor fit: macOS or Windows users
  • Poor fit: Wayland-only desktops, since the README does not describe Wayland support

Install polybar on Debian, Ubuntu, Arch or Fedora

Polybar is available from the package manager of many distributions. The README lists these commands for the most common ones.

On Debian and Ubuntu, use apt. On Arch Linux, use pacman. On Fedora, use dnf. If your distribution is not listed, the README points to building from source, documented in the project wiki.

  • Debian or Ubuntu: install with apt
  • Arch Linux: install with pacman; the latest unstable changes are in the polybar-git package in the AUR
  • Fedora: install with dnf
  • Other distributions: see the Compiling page in the wiki
sudo apt install polybar sudo pacman -S polybar sudo dnf install polybar

Understand how polybar is configured

Polybar is configured through a settings file rather than by writing scripts. The README does not provide a ready-made bar, so expect to set up the bar before it looks useful.

The README points to the project wiki for details on how to run and configure polybar. Check there for the exact file locations and the full list of options for each module.

  • Configuration is done in a settings file, not in scripts
  • The README's default configuration screenshot shows what the project ships as an example
  • Setup and configuration details live in the wiki

Choose modules for your bar

Polybar includes built-in modules for common services. The README lists systray icons, window title, MPD playback, ALSA and PulseAudio volume, bspwm and i3 workspaces, keyboard layout, CPU and memory load, battery, network details, backlight, date and time.

You add the modules you want to your bar. Modules not listed in the README, such as custom script or tail output, are described in the wiki.

  • Workspaces for bspwm and i3, or any EWMH compliant window manager
  • Window title and systray icons
  • Volume via ALSA or PulseAudio
  • Music playback controls for MPD
  • CPU, memory, battery, network, backlight, keyboard layout and date/time

Run polybar and troubleshoot startup

The README says the wiki covers how to run polybar. Once your configuration is in place, start the bar from your session and check that it appears on the edge of your desktop.

If the bar does not appear or a module is missing, first confirm that your window manager is one polybar supports and that your configuration includes the modules you expect. The project's Support page lists where to get help.

  • Confirm you are on Linux with an X11 window manager
  • Check your configuration file against the wiki
  • Look at the Support page for help channels, including Gitter, the r/polybar subreddit, and the #polybar IRC channel on Libera Chat

What people use it for

  • Showing i3 or bspwm workspaces and the window title on a single bar
  • Displaying volume from ALSA or PulseAudio with MPD playback controls
  • Monitoring battery, network connection details, CPU and memory load on a laptop
  • Showing keyboard layout and the date and time in a minimal custom bar

Frequently asked questions

Is polybar free?

Yes. Polybar is licensed under the MIT License, and the source is on GitHub. The project accepts donations through Open Collective, but donations are optional.

How do I install polybar on Ubuntu?

On Ubuntu 20.10 or later, run sudo apt install polybar. On Debian, the same command works on bullseye or later.

Does polybar work on macOS or Windows?

The README and project topics focus on Linux and X11 window managers, so it is not documented for macOS or Windows.

Does polybar work on Wayland?

The README does not describe Wayland support, so do not assume it works on a Wayland-only desktop.

What are alternatives to polybar?

Comparable projects mentioned include i3blocks, Waybar, Eww and Lemonbar. Waybar and Eww are options to consider if you need a different display stack or approach.

Why is my polybar not showing?

Check that you run a supported Linux window manager, that the package installed, and that your configuration file defines a bar. The wiki has setup and configuration details, and the Support page lists places to ask for help.

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

Polybar suits Linux users on i3, bspwm or another EWMH compliant window manager who want a lightweight, customisable bar and are willing to edit a config file. If you use macOS, Windows or a Wayland-only desktop, or want a bar that works with no setup, look at other options.

Install options & downloads