.. highlight:: ini

polybar(5)

Description

The polybar configuration file defines the behavior and look of polybar. It uses a variant of the INI <https://en.wikipedia.org/wiki/INI_file>_ 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.
$XDG_CONFIG_HOME/polybar/config
$XDG_CONFIG_HOME/polybar/config.ini
$HOME/.config/polybar/config
$HOME/.config/polybar/config.ini
$XDG_CONFIG_DIRS/polybar/config.ini
/etc/xdg/polybar/config.ini (only if XDG_CONFIG_DIRS is not set)
/etc/polybar/config.ini

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 :manpage: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 the value of the name key has a leading and trailing whitespace.

To treat characters with special meaning as literal characters, you need to prepend them with the backslash (\) escape character:

name = "value\value\value"

Value of this key name results in value\value\value.

.. note::

The only character with a special meaning right now is the backslash character (\), which serves as the escape character. More will be added in the future.

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, the value of name is actually set to value ; comment:

name = value ; comment

AUTHORS

| Polybar was created by Michael Carlberg and is currently maintained by Patrick Ziegler. | Contributors can be listed on GitHub.

polybar(5)

polybar(5)

Description

Another comment

Syntax

AUTHORS

SEE ALSO