Home

Where to start

For a normal installation, polybar will install the default config to /etc/polybar/config.ini. This config file should be usable out-of-the-box by simply running in your terminal:

polybar

Note: If you have already created your own config in your home directory, polybar will load that.

To get started with your own customization, you need to create a configuration file in ~/.config/polybar/config.ini.

You can copy the default config from /etc/polybar/config.ini or start from scratch.

The config file requires a bar section for each bar you want to define. Each module also has its own module section and can be added to modules-left, modules-center or modules-right in the bar section to have it display on that bar.

See the Configuration wiki page for more details on how to configure the bar.

Running the app

Usage: polybar [OPTION]... [BAR]

  -h, --help                   Display this help and exit
  -v, --version                Display build details and exit
  -l, --log=LEVEL              Set the logging verbosity (default: notice)
                               LEVEL is one of: error, warning, notice, info, trace
  -q, --quiet                  Be quiet (will override -l)
  -c, --config=FILE            Path to the configuration file
  -r, --reload                 Reload when the configuration has been modified
  -d, --dump=PARAM             Print value of PARAM in bar section and exit
  -m, --list-monitors          Print list of available monitors and exit (Removes cloned monitors)
  -M, --list-all-monitors      Print list of all available monitors (Including cloned monitors) and exit
  -w, --print-wmname           Print the generated WM_NAME and exit
  -s, --stdout                 Output data to stdout instead of drawing it to the X window
  -p, --png=FILE               Save png snapshot to FILE after running for 3 seconds

Also see man 1 polybar.

By default, polybar will load the config file from ~/.config/polybar/config.ini, /etc/xdg/polybar/config.ini, or /etc/polybar/config.ini depending on which it finds first.

If you do not specify the name of the bar and your config file only contains a single bar, polybar will display that bar. Otherwise you have to explicitly specify bar name. For example the following command is used to display the bar defined in the [bar/mybar] section in the config.

polybar mybar

Launching the bar in your wm's bootstrap routine

Create an executable file containing the startup logic, for example $HOME/.config/polybar/launch.sh:

#!/usr/bin/env bash

# Terminate already running bar instances
# If all your bars have ipc enabled, you can use 
polybar-msg cmd quit
# Otherwise you can use the nuclear option:
# killall -q polybar

# Launch bar1 and bar2
echo "---" | tee -a /tmp/polybar1.log /tmp/polybar2.log
polybar bar1 2>&1 | tee -a /tmp/polybar1.log & disown
polybar bar2 2>&1 | tee -a /tmp/polybar2.log & disown

echo "Bars launched..."

Make sure you use the name(s) of the bar(s) from your config.

Make it executable:

$ chmod +x $HOME/.config/polybar/launch.sh

If you are using bspwm, add the following line to bspwmrc:

$HOME/.config/polybar/launch.sh

If you are using i3, add the following lines to your configuration:

exec_always --no-startup-id $HOME/.config/polybar/launch.sh

and remove these

bar {
    i3bar_command i3bar
}

The first line executes the startup script; the second disables i3's default bar

Override monitor

By defining a reference to an environment variable you could override the monitor at launch:

[bar/mybar]
monitor = ${env:MONITOR:fallback-value}
....

$ MONITOR=override-value polybar mybar

Dealing with XRandR 1.5+ randomized monitor names

If your polybar configuration uses the monitor configuration variable and sometimes fails to start because XRandR 1.5+ is creating randomized monitor names, you can fix this by specifying the MONITOR environment variable as shown above, and setting it in your launch.sh script like this:

MONITOR=$(polybar -m|tail -1|sed -e 's/:.*$//g')

i3: Make the bar appear below windows

To allow other windows to be placed above the bar, or to avoid having the bar visible when in fullscreen mode, you need to use the following two parameters. Note that it will tell the window manager to back off so no area will be reserved, etc.

[bar/mybar]
override-redirect = true
wm-restack = i3