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 (unreleased).
Table of Contents
"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.
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 If either |
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 |
prev : | Switches to the previous workspace. The behavior of this action is
affected by the |
internal/bspwm¶
focus : | (Has Data) Switches to the given workspace. The data has the form |
---|---|
next : | Switches to the next workspace. The behavior of this action is
affected by the |
prev : | Switches to the previous workspace. The behavior of this action is
affected by the |
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 |
prev : | Switches to the previous workspace. The behavior of this action is
affected by the |
Deprecated Action Names¶
Deprecated since version 3.5.0 (unreleased).
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.
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¶
REPORTING BUGS¶
Report issues on GitHub <https://github.com/polybar/polybar>
SEE ALSO¶
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¶
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¶
- Polybar Wiki
- Gitter
- /r/polybar on reddit
#polybar
onchat.freenode.net