POLYBAR(5)

🌸 NAME 🌸

polybar — the config file for polybar(1) 💅

(Hi bestie, you're reading the Polybar User Manual, aka polybar(5). This is the page that explains how the config file works, and yes it's gonna be a vibe.)

---

✨ DESCRIPTION ✨

Okay so the polybar config file is literally the main character that defines how polybar behaves and how it looks 🎀. It uses a variant of the INI file format — the exact syntax is explained below, but first here's a lil snippet so you can get familiar with the whole situation:

[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 it starts up, polybar goes looking for the config file in a bunch of places, in this exact 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, meaning everything is constrained to a single line 🫶. So no multiline values, no other multiline constructs — the only exception is sections. Every single line is one of these four types:

• Empty
• Comment
• Section Header
• Key

Spaces at the beginning and end of each line get ignored, no cap.

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).

And any line that doesn't fit into one of those four types? That's a syntax error, periodt 💀.

NOTE: It's 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 how you 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 ]). Like this:

[module/wm]

That 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. (Imagine a key with no section... embarrassing.)

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 too, so all of these are literally equivalent:

name=value
name = value
name =      value

And 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"

The 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. Respect the icons fr fr 🌈.

---

⭐ SEE ALSO ⭐

polybar(1), polybar-msg(1)

---

🧚 COPYRIGHT 🧚

2016-2024, Michael Carlberg & contributors

---

And that's the whole page, bestie — this was polybar version 3.7.2 from the Polybar User Manual, dated Sep 10, 2024. Slay, go write a config that ate 💅✨