Polybar Documentation

Note

This is still very much a work-in-progress. Most information is still to be found on our GitHub Wiki. We will migrate the wiki content step-by-step.

Welcome to the official polybar documentation.

polybar(1)

SYNOPSIS

polybar [OPTIONS]… BAR

DESCRIPTION

Polybar aims to help users build beautiful and highly customizable status bars for their desktop environment, without the need of having a black belt in shell scripting.

OPTIONS

-h, --help

Display help text 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

Specify the path to the configuration file. By default, the configuration file is loaded from:


$XDG_CONFIG_HOME/polybar/config
$HOME/.config/polybar/config
-r, --reload

Reload the application when the config file has been modified

-d, --dump=PARAM

Print the value of the specified parameter PARAM in bar section and exit

-m, --list-monitors

Print list of available monitors and exit

If some monitors are cloned, this will exclude all but one of them

-M, --list-all-monitors

Print list of available monitors and exit

This will also include all cloned monitors.

-w, --print-wmname

Print the generated WM_NAME and exit

-s, --stdout

Output the data to stdout instead of drawing it to the X window

-p, --png=FILE

Save png snapshot to FILE after running for 3 seconds

AUTHOR

Michael Carlberg <c@rlberg.se>
Contributors can be listed on GitHub.

REPORTING BUGS

Report issues on GitHub <https://github.com/polybar/polybar>

polybar(5)

Description

The polybar configuration file defines the behavior and look of polybar. It uses a variant of the INI file format. The exact syntax is described below but first a small snippet to get familiar with the syntax:

[section_name]
; A comment
# Another comment

background = #ff992a
width = 90%
monitor = HDMI-0

screenchange-reload = false

; Use double quotes if you want to keep the surrounding space.
text = " Some text "

When started polybar will search for the config file in one of several places in the following order:

  • If the -c or --config command line argument is specified, it will use the path given there.
  • If the environment variable XDG_CONFIG_HOME is set it will use $XDG_CONFIG_HOME/polybar/config
  • If the environment variable HOME is set it will use $HOME/.config/polybar/config

Syntax

The entire config is line-based so everything is constrained to a single line. This means there are no multiline values or other multiline constructs (except for sections). Each line has one of four types:

  • Empty
  • Comment
  • Section Header
  • Key

Spaces at the beginning and end of each line will be ignored.

Note

In this context “spaces” include the regular space character as well as the tab character and any other character for which isspace(3) returns true (e.g. \r).

Any line that doesn’t fit into one of these four types is a syntax error.

Note

It is recommended that section header names and key names only use alphanumeric characters as well as dashes (-), underscores (_) and forward slashes (/).

In practice all characters are allowed except for spaces and any of these: "'=;#[](){}:.$\%

Section Headers

Sections are used to group config options together. For example each module is defined in its own section.

A section is defined by placing the name of the section in square brackets ([ and ]). For example:

[module/wm]

This declares a section with the name module/wm and all keys defined after this line will belong to that section until a new section is declared.

Warning

The first non-empty and non-comment line in the main config file must be a section header. It cannot be a key because that key would not belong to any section.

Note

The following section names are reserved and cannot be used inside the config: self, root, and BAR.

Keys

Keys are defined by assigning a value to a name like this:

name = value

This assigns value to the key name in whatever section this line is in. Key names need to be unique per section. If the value is enclosed by double-quotes ("), the quotes will be ignored. So the following still assigns value to name:

name = "value"

Spaces around the equal sign are ignored, the following are all equivalent:

name=value
name = value
name =      value

Because spaces at the beginning and end of the line are also ignored, if you want your value to begin and/or end with a space, the value needs to be enclosed in double-quotes:

name = " value "

Here name has a leading and trailing whitespace.

Empty Lines & Comments

Empty lines and comment lines are ignored when reading the config file, they do not affect polybar’s behavior. Comment lines start with either the ; or the # character.

Note

Inline comments are not supported. For example the following line does not end with a comment, they value of name is actually set to value ; comment:

name = value ; comment

SEE ALSO

polybar(1)

Packaging Polybar

Do you want to package polybar for a distro? Great! Read this page to get started.

First Steps

Before you get started, have a look at the Packaging Label on our GitHub repo and Repology to see if polybar is already packaged for that distro or if there are efforts to do so.

Even if a package already exists, it might still make sense for you to package polybar in some cases. Some of these cases are:

  • The existing package is out-of-date and the packager is no longer able/willing to continue maintaining the package (or they are simply not reachable anymore).
  • The existing package exist in some non-official repository and you are able to introduce the package into the official package repository for the distro/package manager. For example if there is a PPA providing polybar for Ubuntu and you can add polybar to the official Ubuntu repositories, please do :)

The list above is not exhaustive, if you are unsure, feel free to ask in a new GitHub issue or on Gitter. Please also ask if you run into any polybar related issues while packaging.

Packaging

If you haven’t already, carefully read the Compiling wiki page to make sure you fully understand all the dependencies involved and how to build polybar manually.

We can’t really tell you how to create a package for your distro, you need to figure that out yourself. But we can give you some guidance on building polybar for a package

Gathering the Source Code

Unless you are creating a package that tracks the master branch, don’t clone the git repository. We provide a tarball with all the required source code on our Release Page, use that in your build.

Configuring and Compiling

Note

Do not use the build.sh script for building polybar for your package. The usage and flags of the script may change without notice and we don’t consider that a breaking change.

You can mostly follow the instructions on the wiki for how to compile polybar, but there are some additional cmake arguments you might want to use:

  • -DCMAKE_BUILD_TYPE=Release: As of writing this is already the default, but use it just to be on the safe side.
  • -DCMAKE_INSTALL_PREFIX=/usr: Without this all the polybar files will be installed under /usr/local. However, for packages it is often recommended they directly install to /usr. So this flag will install polybar to /usr/bin/polybar instead of /usr/local/bin/polybar. The packaging guidelines for your distro may disagree with this, in that case be sure to follow your distro’s guidelines.

Instead of sudo make install, you will most likely want to use DESTDIR=<dir> make install. That way the files will be installed into <dir> instead of your filesystem root.

Finishing Up

Finally, subscribe to our GitHub thread for package maintainers to get notified about new releases and changes to how polybar is built. If you want to, you can also open a PR to add your package to the Getting Started section of our README.

Thank you very much for maintaining a polybar package! 🎉

Getting Help