Manpages - polybar.5
Table of Contents
NAME
polybar - configuration file for polybar(1)
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:
#+begin_quote
[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 "
#+end_quote
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.
- $XDG_CONFIG_HOME/polybar/config
- $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:
#+begin_quote 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).
#+end_quote
Any line that doesn’t fit into one of these four types is a syntax error.
NOTE:
#+begin_quote 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: “‘=;#[](){}:.$\%
#+end_quote
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:
#+begin_quote
[module/wm]
#+end_quote
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:
#+begin_quote 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.
#+end_quote
NOTE:
#+begin_quote The following section names are reserved and cannot be used inside the config: self, root, and BAR.
#+end_quote
Keys
Keys are defined by assigning a value to a name like this:
#+begin_quote
name = value
#+end_quote
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:
#+begin_quote
name = "value"
#+end_quote
Spaces around the equal sign are ignored, the following are all equivalent:
#+begin_quote
name=value name = value name = value
#+end_quote
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:
#+begin_quote
name = " value "
#+end_quote
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:
#+begin_quote 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:
#+begin_quote
#+begin_quote
name = value ; comment
#+end_quote #+end_quote #+end_quote
SEE ALSO
polybar(1)
COPYRIGHT
2016-2021, Michael Carlberg & contributors