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.

Actions

New in version 3.5.0.

"Actions" are used to trigger certain behavior in modules. For example, when you click on your volume module (pulseaudio or alsa), polybar internally sends an action to that module that tells it to mute/unmute the audio.

These actions are not only used internally, but users can also send these actions to polybar through Inter Process Communication (IPC) to trigger certain behavior in polybar modules.

Action String Format

An action string follows the following format:

#NAME.ACTION[.DATA]

Where NAME is the name of the target module (not the type!) and ACTION is the name of the action in that module. DATA is optional data attached to an action (for example to say which menu level should be opened).

For example the date module supports the toggle action to toggle between the regular and the alternative time and date format. If you have the following date module:

[module/mydate]
type = internal/date
...

The action string for toggling between the date formats would look like this:

#mydate.toggle

Note that we use the name of the module (mydate) and not the type.

As an example for an action string with additional data, take the menu module:

[module/powermenu]
type = custom/menu
menu-0-0 = Poweroff
menu-0-0-exec = poweroff
menu-0-1 = Suspend
menu-0-1-exec = systemctl suspend

The action name to open a certain menu level is open, so to open level 0 (menu-0), the action string additionally has the level attached to it:

#powermenu.open.0

Triggering Actions

Most modules already use action strings to trigger actions when you click on or scroll over a module. But in some cases you may want or need to manually send action strings to polybar to trigger a certain behavior.

Everywhere where you can specify a command to run on click or scroll, you can also specify an action string. For example, in the bar section, you can specify a command that is triggered when you click anywhere on the bar (where there isn't another click action):

[bar/mybar]
...
click-left = #mydate.toggle
...

This will then trigger the toggle action on the mydate module when you click anywhere on the bar.

Similarly, we can use action strings in %{A} formatting tags just as we would regular commands:

%{A1:firefox:}%{A3:#mydate.toggle:}Opens firefox on left-click and toggles the
date on right-click %{A}%{A}

Finally, polybar's Inter Process Communication (IPC) can also be used to trigger actions:

polybar-msg action "#mydate.toggle"

Note

The quotes around the action string are necessary, otherwise your shell may interpret the # as the beginning of the comment and ignore the rest of the line.

Available Actions

The following modules have actions available. Most of them are already used by the module by default for click and scroll events.

All Modules

These actions are available to all modules and are prefixed with module_.

module_show, module_hide:
 

Shows/Hides a module. The module is still running in the background when hidden, it is just not drawn. The starting state can be configured with the hidden configuration option.

New in version 3.6.0.
module_toggle:

Toggles the visibility of a module.

New in version 3.6.0.

internal/date

toggle:Toggles the date/time format between date/time and date-alt/time-alt

internal/alsa

inc, dec:Increases/Decreases the volume by interval percentage points, where interval is the config setting in the module. Volume changed like this will never go above 100%.
toggle:Toggles between muted and unmuted.

internal/pulseaudio

inc, dec:Increases/Decreases the volume by interval percentage points, where interval is the config setting in the module. Volume changed like this will never go above ~153% (if use-ui-max is set to true) or 100% (if not).
toggle:Toggles between muted and unmuted.

internal/xbacklight

inc, dec:Increases/Decreases screen brightness 5 percentage points.

internal/backlight

inc, dec:Increases/Decreases screen brightness 5 percentage points.

internal/xkeyboard

switch:Cycles through configured keyboard layouts.

internal/mpd

play:

Starts playing the current song.
pause:

Pauses the current song.
stop:

Stops playing.
prev:

Starts playing the previous song.
next:

Starts playing the next song.
repeat:

Toggles repeat mode.
single:

Toggles single mode.
random:

Toggles random mode.
consume:

Toggles consume mode.
seek:

(Has Data) Seeks inside the current song.

The data must be of the form [+-]N, where N is a number between 0 and 100.

If either + or - is used, it will seek forward or backward from the current position by N% (relative to the length of the song). Otherwise it will seek to N% of the current song.

internal/xworkspaces

focus:

(Has Data) Switches to the given workspace.

The data is the index of the workspace that should be selected.
next:

Switches to the next workspace. The behavior of this action is affected by the pin-workspaces setting.
prev:

Switches to the previous workspace. The behavior of this action is affected by the pin-workspaces setting.

internal/bspwm

focus:

(Has Data) Switches to the given workspace.

The data has the form N+M, where N is the index of the monitor and M the index of the workspace on that monitor. Both indices are 0-based and correspond to the position the monitor and workspace appear in the output of bspc subscribe report.
next:

Switches to the next workspace. The behavior of this action is affected by the pin-workspaces setting.
prev:

Switches to the previous workspace. The behavior of this action is affected by the pin-workspaces setting.

internal/i3

focus:

(Has Data) Switches to the given workspace.

The data is the name of the workspace defined in the i3 config.
next:

Switches to the next workspace. The behavior of this action is affected by the pin-workspaces setting.
prev:

Switches to the previous workspace. The behavior of this action is affected by the pin-workspaces setting.

custom/menu

open:

(Has Data) Opens the given menu level

The data is a single number specifying which menu level should be opened.
close:

Closes the menu
exec:

(Has Data) Executes the command at the given menu element.

The data has the form N-M and the action will execute the command in menu-N-M-exec.

custom/ipc

New in version 3.6.0.

send:

(Has Data) Replace the contents of the module with the data passed in this action.
hook:

(Has Data) Trigger the given hook.

The data is the 0-based index of the hook to trigger.
next:

Switches to the next hook and wrap around when the last hook was displayed.
prev:

Switches to the previous hook and wrap around when the first hook was displayed.
reset:

Reset the module to its startup state: either empty or according to the initial setting.

Deprecated Action Names

Deprecated since version 3.5.0.

In earlier versions (< 3.5.0) action strings only included information about the module type. This meant in bars that contained multiple different modules of the same type, actions for these modules were sometimes processed by the wrong module with the same type.

Since version 3.5.0, this no longer happens. However, this also means we had to change what actions are recognized by polybar modules.

If you explicitly use any polybar action names in your config or any of your scripts, you are advised to change them, as they may stop working at some point in the future. For now polybar still supports the old action names, will convert them to the appropriate new action name, and will print a warning to help you find old action names in your config.

If you use the menu module, you most likely use old action names to open and close the menu (for example menu-open-1 or menu-close). The i3wm-wsnext, i3wm-wsprev, bspwm-desknext, and bspwm-deskprev actions, to switch workspaces in i3 and bspwm, may also appear in your config.

Migration

Updating your config to use the new action names is quite straightforward.

For each action name, consult the table below to find the new action name. Afterwards build the complete action string as described in Action String Format.

Please see below for an example of migrating a typical menu module.

Module Type Deprecated Action Name New Action Name
internal/date datetoggle toggle
internal/alsa volup inc
voldown dec
volmute toggle
internal/pulseaudio pa_volup inc
pa_voldown dec
pa_volmute toggle
internal/xbacklight xbacklight+ inc
xbacklight- dec
internal/backlight backlight+ inc
backlight- dec
internal/xkeyboard xkeyboard/switch switch
internal/mpd mpdplay play
mpdpause pause
mpdstop stop
mpdprev prev
mpdnext next
mpdrepeat repeat
mpdsingle single
mpdrandom random
mpdconsume consume
mpdseekN seek.N
internal/xworkspaces xworkspaces-focus=N focus.N
xworkspaces-next next
xworkspaces-prev prev
internal/bspwm bspwm-deskfocusN focus.N
bspwm-desknext next
bspwm-deskprev prev
internal/i3 i3wm-wsfocus-N focus.N
i3-wsnext next
i3-wsprev prev
custom/menu menu-open-N open.N
menu-close close

Note

Some deprecated action names are suffixed with N, this means that that action has some additional data (represented by that N), in the new action names this data will appear in exactly the same way, after a period.

Inter-process-messaging

Polybar supports controlling parts of the bar and its modules from the outside through inter-process-messaging (IPC).

IPC is disabled by default and can be enabled by setting enable-ipc = true in the bar section.

By default polybar ships with the polybar-msg tool that is needed to send messages to polybar.

Note

Starting with version 3.6.0, the underlying IPC mechanism has been completely changed.

Writing directly to the named pipe to send IPC messages has been deprecated, polybar-msg should be used exclusively Everything you could do by directly writing to the named pipe, you can also do using polybar-msg. In addition, hook messages are also deprecated; they are replaced by actions on the ipc module.

Unless noted otherwise, everything in this guide is still valid for older versions.

Sending Messages

polybar-msg can be called on the commandline like this:

polybar-msg [-p <pid>] <type> <payload>

If the -p argument is specified, the message is only sent to the running polybar instance with the given process ID. Otherwise, the message is sent to all running polybar processes that have IPC enabled.

Note

IPC messages are only sent to polybar instances running under the same user as polybar-msg is running as.

Concretely, polybar and polybar-msg use the $XDG_RUNTIME_DIR environment variable in accordance with the XDG Base Directory Specification to determine where to find the socket to communicate.

If polybar and polybar-msg don't have the same value for $XDG_RUNTIME_DIR, they will likely not be able to communicate. The variable may not be set if you use su or sudo to execute polybar-msg as a different user, often a full user session is required.

The <type> argument is either action or cmd. The allowed values for <payload> depend on the type.

Message Types

Commands

Using cmd for <type>, you can control certain aspects of the bar.

Available values for <payload> are:

  • quit: Terminates the bar
  • restart: Restarts the bar in-place
  • hide: Hides the bar
  • show: Makes the bar visible again, if it was hidden
  • toggle: Toggles between the hidden and visible state.

Module Actions

For the <type> action, polybar-msg can execute module actions in the bar.

An action consists of the name of the target module, the name of the action and an optional data string:

#<modulename>.<actionname>[.<data>]

More information about action strings and available actions can be found in Actions

For example, if you have a date module named date, you can toggle between the regular and alternative label with:

polybar-msg action "#date.toggle"

As an example for an action with data, say you have a menu module named powermenu, you can open the menu level 0 using:

polybar-msg action "#powermenu.open.0"

Note

For convenience, polybar-msg also allows you to pass the module name, action name, and data as separate arguments:

polybar-msg action date toggle
polybar-msg action powermenu open 0

New in version 3.6.0.

Modules

Tray Module

type = internal/tray

New in version 3.7.0 (unreleased).

The tray module displays system tray application icons on the bar.

This module is a bit different from the other modules. The tray icons (also called clients) are individual windows managed by their respective application (e.g. the Dropbox tray icon is created and managed by the Dropbox application). Polybar is only responsible for embedding the windows in the bar and positioning them correctly.

Note

Only a single instance of this module can be active at the same time (across all polybar instances).

The way the system tray protocol works, at most one tray can exist at any time. Polybar will produce a warning if additional tray instances are created.

For transparent background colors, the tray will use pseudo-transparency, true transparency is not possible for the tray icons.

Formats

The module only has a single format:

format
Type:format
Available Tags:<tray>: Shows tray icons
Default Value:<tray>

Settings

tray-spacing

Space added between tray icons

Type:extent, non-negative
Default Value:0px
tray-padding

Space added before and after each tray icon

Type:extent, non-negative
Default Value:0px
tray-size

Size of individual tray icons

Type:percentage with offset, relative to bar height, non-negative
Default Value:66%
tray-background

Background color of tray icons

Note

This only affects the color of the individual icons and not the space in between, changing this setting to anything else than the bar background will likely not look good unless the background color is also changed for the rest of the tray module (e.g. with format-background).

Type:color
Default Value:${root.background}
tray-foreground

Tray icon color

This serves as a hint to the tray icon application for which color to use for the icon.

This is not guaranteed to have any effect (likely only in GTK3) because it targets a non-standard part of the system tray protocol by setting the _NET_SYSTEM_TRAY_COLORS atom on the tray window.

Type:color
Default Value:${tray-foreground}

Example

[module/tray]
type = internal/tray

format-margin = 8px
tray-spacing = 8px

Migrating From Legacy Tray Implementation

Polybar version 3.7 introduced the new tray module and deprecated the legacy tray implementation which uses tray-position to position the tray. You should switch over to the tray module as soon as possible.

The legacy tray was configured in the bar section, the setting for the module live in that module's section of the config file. The settings in the bar section don't always directly correspond to an equivalent setting in the module section for the new tray module.

The following lists how each old setting in the bar section should be migrated:

tray-position
The tray is now positioned as a module and so its positioning is done by placing it where you want it to appear in one of the three module lists modules-left, modules-center, modules-right.
tray-detached
This setting does not have an equivalent, detaching the tray is no longer possible.
tray-maxsize
The tray-size setting now determines the size of tray icons.
tray-transparent
Was already deprecated and does not exist in the tray module. Transparency is enabled automatically if a transparent background is used.
tray-background
Also exists in the module section (see tray-background). Now, the setting only applies to the icons themselves and no longer to the space around them.
tray-foreground
Also exists in the module section with the same functionality (see tray-foreground).
tray-offset-x, tray-offset-y

Has no direct equivalent in the module settings. Horizontally, the tray can be moved in the same way other module content can be moved; by reordering the modules or using things like format-offset, format-margin, or format-padding. The tray can't be moved vertically.

In any case, the tray can no longer be moved outside of the bar window.

tray-padding
Spacing between tray icons works a bit different now and needs to be completely reconfigured (see tray-padding and tray-spacing).
tray-scale
No longer exist. The size of the icons is solely determined by tray-size.

Default Configuration

New in version 3.6.0.

Polybar's default configuration lives in /etc/polybar/config.ini and is loaded if no other configuration file can be found.

Screenshot of default polybar configuration
Download
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
;==========================================================
;
;
;   ██████╗  ██████╗ ██╗  ██╗   ██╗██████╗  █████╗ ██████╗
;   ██╔══██╗██╔═══██╗██║  ╚██╗ ██╔╝██╔══██╗██╔══██╗██╔══██╗
;   ██████╔╝██║   ██║██║   ╚████╔╝ ██████╔╝███████║██████╔╝
;   ██╔═══╝ ██║   ██║██║    ╚██╔╝  ██╔══██╗██╔══██║██╔══██╗
;   ██║     ╚██████╔╝███████╗██║   ██████╔╝██║  ██║██║  ██║
;   ╚═╝      ╚═════╝ ╚══════╝╚═╝   ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝
;
;
;   To learn more about how to configure Polybar
;   go to https://github.com/polybar/polybar
;
;   The README contains a lot of information
;
;==========================================================

[colors]
background = #282A2E
background-alt = #373B41
foreground = #C5C8C6
primary = #F0C674
secondary = #8ABEB7
alert = #A54242
disabled = #707880

[bar/example]
width = 100%
height = 24pt
radius = 6

; dpi = 96

background = ${colors.background}
foreground = ${colors.foreground}

line-size = 3pt

border-size = 4pt
border-color = #00000000

padding-left = 0
padding-right = 1

module-margin = 1

separator = |
separator-foreground = ${colors.disabled}

font-0 = monospace;2

modules-left = xworkspaces xwindow
modules-right = filesystem pulseaudio xkeyboard memory cpu wlan eth date

cursor-click = pointer
cursor-scroll = ns-resize

enable-ipc = true

; tray-position = right

; wm-restack = generic
; wm-restack = bspwm
; wm-restack = i3

; override-redirect = true

[module/xworkspaces]
type = internal/xworkspaces

label-active = %name%
label-active-background = ${colors.background-alt}
label-active-underline= ${colors.primary}
label-active-padding = 1

label-occupied = %name%
label-occupied-padding = 1

label-urgent = %name%
label-urgent-background = ${colors.alert}
label-urgent-padding = 1

label-empty = %name%
label-empty-foreground = ${colors.disabled}
label-empty-padding = 1

[module/xwindow]
type = internal/xwindow
label = %title:0:60:...%

[module/filesystem]
type = internal/fs
interval = 25

mount-0 = /

label-mounted = %{F#F0C674}%mountpoint%%{F-} %percentage_used%%

label-unmounted = %mountpoint% not mounted
label-unmounted-foreground = ${colors.disabled}

[module/pulseaudio]
type = internal/pulseaudio

format-volume-prefix = "VOL "
format-volume-prefix-foreground = ${colors.primary}
format-volume = <label-volume>

label-volume = %percentage%%

label-muted = muted
label-muted-foreground = ${colors.disabled}

[module/xkeyboard]
type = internal/xkeyboard
blacklist-0 = num lock

label-layout = %layout%
label-layout-foreground = ${colors.primary}

label-indicator-padding = 2
label-indicator-margin = 1
label-indicator-foreground = ${colors.background}
label-indicator-background = ${colors.secondary}

[module/memory]
type = internal/memory
interval = 2
format-prefix = "RAM "
format-prefix-foreground = ${colors.primary}
label = %percentage_used:2%%

[module/cpu]
type = internal/cpu
interval = 2
format-prefix = "CPU "
format-prefix-foreground = ${colors.primary}
label = %percentage:2%%

[network-base]
type = internal/network
interval = 5
format-connected = <label-connected>
format-disconnected = <label-disconnected>
label-disconnected = %{F#F0C674}%ifname%%{F#707880} disconnected

[module/wlan]
inherit = network-base
interface-type = wireless
label-connected = %{F#F0C674}%ifname%%{F-} %essid% %local_ip%

[module/eth]
inherit = network-base
interface-type = wired
label-connected = %{F#F0C674}%ifname%%{F-} %local_ip%

[module/date]
type = internal/date
interval = 1

date = %H:%M
date-alt = %Y-%m-%d %H:%M:%S

label = %date%
label-foreground = ${colors.primary}

[settings]
screenchange-reload = true
pseudo-transparency = true

; vim:ft=dosini

Polybar Migration Guides

Updating polybar to the newest version often requires updating your configuration files to use the newest features and replace outdated settings.

Starting from version 3.7, we include a small guide here for how to migrate from the previous version. If you are upgrading over multiple versions (e.g. from 3.5 to 3.7), also read the migration guides for all versions in between.

For migration guides before version 3.7, please look at our release blog posts.

When upgrading make sure to run polybar from the terminal and look for errors, warnings, and deprecation messages. This can save you a lot of issues in the future when deprecated settings and features are removed.

Migrating From Version 3.6 to 3.7

System Tray

Polybar version 3.7 introduced the new tray module and deprecated the legacy tray implementation which uses tray-position to position the tray. You should switch over to the tray module as soon as possible.

The legacy tray was configured in the bar section, the setting for the module live in that module's section of the config file. The settings in the bar section don't always directly correspond to an equivalent setting in the module section for the new tray module.

The following lists how each old setting in the bar section should be migrated:

tray-position
The tray is now positioned as a module and so its positioning is done by placing it where you want it to appear in one of the three module lists modules-left, modules-center, modules-right.
tray-detached
This setting does not have an equivalent, detaching the tray is no longer possible.
tray-maxsize
The tray-size setting now determines the size of tray icons.
tray-transparent
Was already deprecated and does not exist in the tray module. Transparency is enabled automatically if a transparent background is used.
tray-background
Also exists in the module section (see tray-background). Now, the setting only applies to the icons themselves and no longer to the space around them.
tray-foreground
Also exists in the module section with the same functionality (see tray-foreground).
tray-offset-x, tray-offset-y

Has no direct equivalent in the module settings. Horizontally, the tray can be moved in the same way other module content can be moved; by reordering the modules or using things like format-offset, format-margin, or format-padding. The tray can't be moved vertically.

In any case, the tray can no longer be moved outside of the bar window.

tray-padding
Spacing between tray icons works a bit different now and needs to be completely reconfigured (see tray-padding and tray-spacing).
tray-scale
No longer exist. The size of the icons is solely determined by tray-size.

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. If the BAR argument is not provided and the configuration file only contains one bar definition, polybar will display this bar.

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
  • $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
-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.
If polybar was compiled with RandR monitor support, only monitors are listed and not physical outputs.
-M, --list-all-monitors
Print list of all available monitors and exit.
This includes cloned monitors as well as both physical outputs and RandR monitors (if supported).
Only the names listed here can be used as monitor names in polybar.
-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

AUTHORS

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

REPORTING BUGS

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

polybar-msg(1)

SYNOPSIS

polybar-msg [OPTIONS] action action-string
polybar-msg [OPTIONS] action module action [data]
polybar-msg [OPTIONS] cmd command

DESCRIPTION

Polybar allows external control through actions and commands. Actions control individual modules and commands control the bar itself.

The full IPC documentation is linked at the end of this document.

The available actions depend on the target module. For actions, the payload is either a single action string or the module name, the action name, and the optional data string specified separately.

In order for polybar-msg being able to send a message to a running polybar process, the bar must have IPC enabled and both polybar-msg and polybar must run under the same user.

OPTIONS

-h, --help

Display help text and exit

-p PID

Send message only to polybar process running under the given process ID. If not specified, the message is sent to all running polybar processes.

EXAMPLES

polybar-msg cmd quit
Terminate all running polybar instances.

polybar-msg action mymodule module_hide

polybar-msg action "#mymodule.module_hide"
Hide the module named mymodule. The first variant specifies the module and action names separately, the second uses an action string.

AUTHORS

Polybar was created by Michael Carlberg and is currently maintained by Patrick Ziegler.
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.
  • $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 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.

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 Started

Setting up polybar for development is basically the same process as compiling it from source. However, we recommend using the Debug or Sanitize cmake build type when configuring the project:

cmake -DCMAKE_BUILD_TYPE=Debug ..
# Or
cmake -DCMAKE_BUILD_TYPE=Sanitize ..

This will give you debug symbols in the executable and the Sanitize build type will also enable the AddressSanitizer and UndefinedBehaviorSanitizer, which can give you very useful information about crashes and undefined behavior at runtime.

Editors

Since this is a cmake project, most IDEs will have built-in support or a plugin to automatically setup this project.

In addition, the cmake command creates a compile_commands.json file in the build folder, which can be used by many language servers. If you are using a C++ language server in your editor, it should be as easy as symlinking the compile_commands.json into the repo root directory:

ln -s build/compile_commands.json .

Distro-Specific Setup

The wiki contains user-contributed setup tips for some distros.

Style Guide

There is a .editorconfig and a .clang-format file in the project root that defines some basic guidelines, mainly relating to indentation.

Code Formatting

We use clang-format for code formatting, the style rules are defined in .clang-format, before submitting a PR, make sure to run the following command on all the C++ files you changed:

clang-format -style=file -i <FILES>

Note: Depending on which file you change, this may produce a lot of changes because we have not run clang-format on all files in the project. This is fine.

Indentation

Files use 2 spaces for indentation.

Line Width

Lines should not be longer than 120 characters, clang-format will enforce this when run. However, try to keep lines under 80 characters if it seems reasonable in the current situation.

In some cases it makes sense to have lines longer than 80 characters for readability. But long lines can just the same be unreadable, for example if you have long if-conditions or use complex expressions as function parameters. Make sure you only use longer lines if keeping it under 80 would be less readable.

Comments

Use Doxygen /** */ comments in front of functions, methods, types, members and classes:

/**
 * @brief Generates a config object from a config file
 *
 * For modularity the parsing and storing of the config is separated
 */
class config_parser {
...
  /**
   * @brief Is used to resolve ${root...} references
   */
  string m_barname;
...
}

For all other comments use // for single-line and /* */ for multi-line comments.

Your comments should describe the intent and purpose of your code, not necessarily what it does.

Header Files

Header files should end in .hpp.

We use pragmas instead of include guards to guarantee header files are included only once:

#pragma once

Testing

Polybar uses googletest as its testing and mocking framework. Tests live in the tests/ directory; they can be enabled during cmake with -DBUILD_TESTS=ON and compiled with make all_unit_tests.

Each test gets its own executable in build/tests, which can be executed to run a specific test.

Running all tests is preferably done with the following command:

make check

This runs all available tests and prints the output in color for failed tests only.

Adding New Tests

All new tests need to be added to the tests/CMakeLists.txt file. Have a look at the other unit tests in tests/unit_tests to see how to write tests for your code.

Release Workflow

We try to follow Semantic Versioning in this project. Patch releases (e.g. 3.3.X) contain only bug fixes. Minor releases (e.g. 3.X.0) can have backwards-compatible features. And major releases ( X.0.0) can introduce incompatible changes.

Note

This document replaces the "Release Guidelines" on the wiki that we used between 3.2.0 and 3.4.3. Starting with 3.5.0, we will follow the workflow described here to publish releases.

Polybar uses the OneFlow branching model for publishing new releases and introducing hotfixes.

The way we accept code from contributors does not change: Contributors fork polybar, commit their changes to a new branch and open a PR to get that branch merged. After reviewing and approving the changes, a maintainer "merges" the PR. "Merging" is done in the GitHub UI by either rebasing or squashing the changes. Regular merging is disabled because we do not want merge a merge commit for every PR.

This document is mainly concerned with how to properly release a new version of polybar. For that reason this might not be of interest to you, if you are not a maintainer, but feel free to read on anyway.

Drafting a new Release

There a two processes for how to draft a new release. The process for major and minor versions is the same as they both are "regular" releases. Patch releases are triggered by bugfixes that cannot wait until the next regular release and have a slightly different workflow.

Regular Releases (Major, Minor)

Regular releases are created once we find that master is in a stable state and that there are enough new features to justify a new release. A release branch release/X.Y.0 is branched off of a commit on master that contains all the features we want in the release, this branch is pushed to the official repository. For example for version 3.5.0 the branch release/3.5.0 would be created:

git checkout -b release/3.5.0 <commit>

The release branch should typically only exist for at most a few days.

Hotfix Releases (Patch)

A hotfix release is created whenever we receive a fix for a bug that we believe should be released immediately instead of it only being part of the next regular release. Generally any bugfix qualifies, but it is up to the maintainers to decide whether a hotfix release should be created.

The hotfix release branch hotfix/X.Y.Z is created by branching off at the previous release tag (X.Y.Z-1). For example, if the latest version is 3.5.2, the next hotfix will be on branch hotfix/3.5.3:

git checkout -b hotfix/3.5.3 3.5.2

Since the PRs for such bugfixes are often not created by maintainers, they will often not be based on the latest release tag, but just be branched off master because contributors don't necessarily know about this branching model and also may well not know whether a hotfix will be created for a certain bugfix.

In case a PR containing a bugfix that is destined for a patch release is not branched off the previous release, a maintainer creates the proper release branch and cherry-picks the bugfix commits.

Note

Alternatively, the contributor can also git rebase --onto to base the branch off the previous release tag. However, in most cases it makes sense for a maintainer to create the release branch since they will also need to add a Release Commit to it.

Once the release branch is created and contains the right commits, the maintainer should follow Publishing a new Release to finish this patch release.

If multiple bugfixes are submitted in close succession, they can all be cherry-picked onto the same patch release branch to not create many individual release with only a single fix. The maintainer can also decide to leave the release branch for this patch release open for a week in order to possibly combine multiple bugfixes into a single release.

Publishing a new Release

The process for publishing a release is the same for all release types. It goes as follows:

  • A Release commit is added to the tip of the release branch.
  • A draft PR is opened for the release branch. This PR MUST NOT be merged in GitHub's interface, it is only here for review, merging happens at the commandline.
  • After approval, a signed git tag is created locally at the tip of the release branch and pushed:
git tag -s X.Y.Z <release-branch>
git push --tags
  • A draft release targetting the new tag is created in GitHub's release publishing tools and published.
  • After the tag is created, the release branch is manually merged into master. Here it is vitally important that the history of the release branch does not change and so we use git merge. We do it manually because using git merge is disabled on PRs.
git checkout master
git merge <release-branch>
git push origin
  • After the tag is created, the release branch can be deleted with git push origin :<release-branch>.
  • Work through the After-Release Checklist.

Here <release-branch> is either a release/X.Y.0 branch or a hotfix/X.Y.Z branch.

Release Commit

When merging, a release commit must be at the tip of the release branch.

The release commit needs to update the version number in:

  • version.txt

The release commit must also finalize the Changelog for this release.

Changelog

The CHANGELOG.md file at the root of the repo should already contain all the changes for the upcoming release in a format based on keep a changelog. For each release those changes should be checked to make sure we did not miss anything.

For all releases, a new section of the following form should be created below the Unreleased section:

## [X.Y.Z] - YYYY-MM-DD

In addition, the reference link for the release should be added and the reference link for the unreleased section should be updated at the bottom of the document:

[Unreleased]: https://github.com/polybar/polybar/compare/X.Y.Z...HEAD
[X.Y.Z]: https://github.com/polybar/polybar/releases/tag/X.Y.Z

Since the release tag doesn't exist yet, both of these links will be invalid until the release is published.

All changes from the Unreleased section that apply to this release should be moved into the new release section. For regular releases this is generally the entire Unreleased section, while for patch releases it will only be a few entries.

The contents of the release section can be copied into the draft release in GitHub's release tool with a heading named ## Changelog.

Since major releases generally break backwards compatibility in some way, their changelog should also prominently feature precisely what breaking changes were introduced. If suitable, maybe even separate documentation dedicated to the migration should be written.

Draft Release

On GitHub a new release should be drafted. The release targets the git tag that was just pushed, the name of the release and the tag is simply the release number.

The content of the release message should contain the changelog copied from CHANGELOG.md under the heading ## Changelog. In addition using GitHub's "Auto-generate release notes" feature, the list of new contributors should be generated and put at the end of the release notes. The generated list of PRs can be removed.

After-Release Checklist

  • Verify the release archive (see Verify Release)
  • Make sure all the new functionality is documented on the wiki
  • Mark deprecated features appropriately (see Deprecations)
  • Remove all unreleased notes from the wiki (not for patch releases)
  • Inform packagers of new release in #1971. Mention any dependency changes and any changes to the build workflow. Also mention any new files are created by the installation.
  • Create a PR that updates the AUR PKGBUILD file for the polybar-git package (push after the release archive is uploaded).
  • Close the GitHub Milestone for the new release and move open issues (if any) to a later release.
  • Activate the version on Read the Docs and deactivate all previous versions for the same minor release (e.g. for 3.5.4, deactivate all other 3.5.X versions).

Verify Release

Confirm that the release archive was added to the release. We have a GitHub action workflow called 'Release Workflow' that on every release automatically creates a release archive, uploads it to the release, and adds a 'Download' section to the release body. If this fails for some reason, it should be triggered manually.

Afterwards, download the archive, verify its hash, and sign it:

gpg --armor --detach-sign polybar-X.Y.Z.tar.gz

Finally, upload the generated polybar-X.Y.Z.tar.gz.asc to the GitHub release.

Deprecations

If any publicly facing part of polybar is being deprecated, it should be marked as such in the code, through warnings/errors in the log, and by comments in the wiki. Every deprecated functionality is kept until the next major release and removed there, unless it has not been deprecated in a minor release before.

Getting Help