Polybar: A Better WM Panel for your Linux system


Install and configure Polybar.


Polybar isn’t packaged for many distributions, but you can compile it from source on any of them.


A working Linux install with root privileges.




  • # – requires given linux commands to be executed with root privileges either directly as a root user or by use of sudo command
  • $ – requires given linux commands to be executed as a regular non-privileged user


If you’ve been using a window manager(tiling or otherwise), or you’re thinking about it, you’ve probably looked into different options for menu bars. Most window managers either don’t come with one, or they’re packaged with something that’s not all that useful. Polybar is an excellent answer.

Polybar is entirely independent, but it was specifically designed for compatibility with i3 and BSPWM. You can use it with others, though. It’ll just require some additional configuration on tiling window managers.

Polybar is both flexible and simple. It doesn’t require any complex scripts, but you can create custom module with scripts, if you choose. It’s also easy to make Polybar look good and fit in with your desktop’s theme.

Download Build Dependencies

Polybar is a fairly new program, and it’s not packaged for many distributions yet. It is available for Arch through the AUR. Gentoo has some ebuilds available. If you’re on Debian or Ubuntu, the GetDeb repository has it available too. Everyone else needs to build it.

If you don’t particularly like or trust those sources, you can built it yourself too. You can find the source and dependencies on the project’s Github Page.

Configuring Polybar

Once you have Polybar installed, you’re going to need to configure it. One of the great strengths of Polybar is the flexibility that configuration gives you with relatively minimal effort.

Get The Default Config

It’s best to start off using an existing configuration file as the basis of your configuration. You can do this one of two ways. You can copy the default configuration and modify it, or you can copy the default configuration and copy chunks of it over into a new file that will become your configuration. Either works, so pick whichever one suits your style.

No matter which you choose, you’re going to need to grab the default configuration. First, create the configuration directory, if it’s not already there.

$ mkdir  ~/.config/polybar/

Then, unpack the default configuration into that folder.

$ cd ~/.config/polybar
$ $ sudo gzip -d /usr/share/doc/polybar/config.gz ~/.config/polybar/config

Polybar Default Configuration


Colors are an obvious first thing that you’ll want to modify.

There’s a couple of ways to handle colors. Take a look at the default config. The [colors] section should look like the example below.

;background = ${xrdb:color0:#222}
background = #222
background-alt = #444
;foreground = ${xrdb:color7:#222}
foreground = #dfdfdf
foreground-alt = #555
primary = #ffb52a
secondary = #e60053
alert = #bd2c40

Notice the two different ways the colors are set. One just uses plain hex codes. The other imports colors from .Xresources. That one’s probably the most efficient, and it guarantees that Polybar will always match your system’s color scheme.

It’s also important to note that those values are being assigned to variables. You can reuse those variables throughout the configuration to make your life easier and keep your color scheme unified. In theory, you can set this up so you can change a color once in .Xresources, and it will take effect through all of your X applications and every use in your Polybar configuration.

The Bar

You can define multiple bars in the same configuration file. To define them, create a block, similar to the [colors] one. The default bar in the configuration is
. Take a look at it.

;monitor = ${env:MONITOR:HDMI-1}
width = 100%
height = 27
;offset-x = 1%
;offset-y = 1%
radius = 6.0
fixed-center = false

background = ${colors.background}
foreground = ${colors.foreground}

line-size = 3
line-color = #f00

border-size = 4
border-color = #00000000

padding-left = 0
padding-right = 2

module-margin-left = 1
module-margin-right = 2

font-0 = fixed:pixelsize=10;1
font-1 = unifont:fontformat=truetype:size=8:antialias=false;0
font-2 = siji:pixelsize=10;1

modules-left = bspwm i3
modules-center = xwindow
modules-right = filesystem xbacklight volume xkeyboard memory cpu wlan eth battery temperature date powermenu

tray-position = right
tray-padding = 2
;tray-transparent = true
;tray-background = #0063ff

;wm-restack = bspwm
;wm-restack = i3

;override-redirect = true

;scroll-up = bspwm-desknext
;scroll-down = bspwm-deskprev

;scroll-up = i3wm-wsnext
;scroll-down = i3wm-wsprev

The name of the bar is “example.” You can define the name as anything that you want. Remember it, though, because you’ll use it when you launch the bar.

There are a few important parts here to break down.

First, the top section handles the size and positioning of the bar. There is a line that’s commented out to specify which monitor to display the bar on. That’s important to remember when using multiple monitors.

The rest of the section is fairly self explanatory. The radius option handles rounding the corners of the bar, and fixed-center tells Polybar to keep the center modules section in the same place, regardless of the amount of modules.

The next couple of sections let you set the foreground and background colors as well as a few other style-related values. The padding variables refer to the padding of the bar as a whole, and the module margins are the margins of each individual module. Be more conservative with those values.

The default fonts aren’t all that commonly used. You might want to change them to fonts that you know you have installed. It’s a good idea to have at least one text font and one icon font. Something like Font Awesome works very well for icons.

Following that, there’s the module alignment section. It lets you choose where Polybar will display each of the modules. A bar has a left, center, and right section. List the modules where you want them to appear.

Finally, you have a short section concerning your tray and the tray icons. Choose how you want Polybar to handle the tray.

If you’re using i3 or BSPWM, uncomment the wm-restack and scroll options that match your WM.

Built-In Modules

Now that you have an idea of how to set up your bar, it’s time to take a look at the modules that come with Polybar. Actually, Polybar has you covered for most of the information that you’d want to display in a status bar.

Polybar Filesystem Module

The advantage of the built-in modules is they should all work out-of-the-box with very little modification or configuration. Just change the icons and labels to fit your style, and you’ll be well on your way to a fully customized Polybar.

Polybar i3 Workspaces

If you’re using i3 or BSPWM, they each have a module that integrates functionality from the WM, like displaying the workspaces. The defaults really aren’t great here, so you’ll want to customize them, somewhat. Take a look at this example.

type = internal/i3
enable-click = true
enable-scroll = false
strip-wsnumbers = true
format =  
pin-workspaces = true

ws-icon-0 = 1; 
ws-icon-1 = 2;
ws-icon-2 = 3;♪
ws-icon-3 = 4;
ws-icon-4 = 5;
ws-icon-5 = 6;
ws-icon-6 = 7;
ws-icon-9 = 10;

label-focused = %name%
label-focused-padding = 2
label-focused-margin = 0.5
label-focused-foreground = ${colors.white}
label-focused-underline = ${colors.white}

label-unfocused = %name%
label-unfocused-padding = 2
label-unfocused-margin = 0.5
label-unfocused-underline = ${colors.l_gray}
label-visible-padding = 2
label-visible-margin = 0.5

label-urgent = %name%
label-urgent-padding = 2
label-urgent-margin = 0.5
label-urgent-foreground = ${colors.red}
label-urgent-underline = ${colors.red}

As you can see, you can set Polybar to display your workspace icons to match the ones you set in your i3/BSPWM configuration. Both window managers can be configured similarly. There’s a lot of different ways to handle this module, so feel free to explore.

Custom Modules

If a module doesn’t quite fit your needs, or you want to make something altogether custom, you can. Polybar supports displaying command line output into its own module. This could be from a Bash script, or something more complex. Polybar mostly just reads and formats output. Take a look at this real example.

type = custom/script
exec = /home/nick/.config/polybar/pub-ip.sh
interval = 100
format-underline = ${colors.white}
format = 

As you can see, in order to define a custom module, you just need to set the type of the module. Then, you need to point Polybar at the script that it needs to execute. The interval is the refresh rate, and everything else defines how the output is formatted and displayed.

In case you’re wondering, this is the script that the module executes.

#! /bin/bash

IP=$(dig +short myip.opendns.com @resolver1.opendns.com)

if pgrep -x openvpn > /dev/null; then
    echo VPN: $IP
    echo   $IP

Polybar Public IP Module

It’s nothing complex. It just checks if OpenVPN is running and retrieves the public IP address from OpenDNS. This is the exact kind of thing that you’d want to create a module for, though.

Starting Polybar

Polybar Complete Configuration

Starting Polybar is very easy. Call it with the name of the bar that you want to start.

$ polybar example

You can start Polybar by default with your WM by either adding it to .xinitrc or to your window manager’s configuration file using the same command as above.

Closing Thoughts

You’ve gone through a lot here, and you’ve only scratched the surface. However, you should have a decent enough understanding to construct your own configuration and dig deeper on your own into all of the awesome things that you can do with Polybar.

Comments and Discussions
Linux Forum