Skip to content

Configuration

patrick96 edited this page May 6, 2019 · 80 revisions

The parameters below are using the default values unless stated otherwise. If the key is undefined (commented out) or its value is empty, it means there is no default value for the given parameter.

Syntax and Domain Specific Language

The configuration uses the INI file format.

[section/name]
str = My string
bool = true
bool = on
int = 10
float = 10.0

; Quote string values if you want to keep surrounding spaces
str = "   My string"

; Lists are defined using a 0-based index
mylist-0 = value
mylist-1 = value
mylist-2 = value
; Lists cannot have gaps. To define mylist-4 
; you will also have to define mylist-3

Referencing values

; You can reference a value in another section using:
key = ${section.key}

; Values in the same section can be referenced using:
key = ${self.key}

; Values for a defined bar can be referenced using:
key = ${bar/top.foreground}

; Values for the current bar can be referenced using:
key = ${root.foreground}

; Environment variables can be referenced using:
key = ${env:VAR:fallback value}

; Values in the X resources db can be referenced using:
; NOTE: Requires `xcb-util-xrm`
; Example: 
; Polybar config:
;     background = ${xrdb:color2:#00ff00}
; .Xresources:
;     *color2: #8C9440
key = ${xrdb:KEY:fallback value}

; File contents can be referenced using:
key = ${file:/absolute/file/path:fallback value}

Inheritance

Values can be inherit from another section by defining the parameter inherit = section/base. All undefined keys will be cloned.

[section/base]
foo = 1
bar = 0.15
baz = true

[section/child]
inherit = section/base
baz = false

; Result
[section/child]
foo = 1
bar = 0.15
baz = false

File inclusion

It is possible to include a file with pre-defined key-value pairs using:

[section/base]
include-file = /absolute/path/to/file

Custom variables

; You can create your own local variables, for example:
[colors]
black = #000
white = #fff
blue = #00f
green = #0f0

[modules/tmp]
format-background = ${colors.black}
format-foreground = ${colors.white}

Using the same module for multiple bars

If you are using the same module for more than one bar, there's a neat way to make bar specific changes to the module configuration. Define some custom parameters, for both bars, and then reference them from the module. For example:

[bar/top]
myscript-background = #f00
myscript-command = whoami

[bar/bottom]
myscript-background = #f00
myscript-command = date +%s

[module/myscript]
format-background = ${root.myscript-background}
exec = ${root.myscript-command}

Bar settings

Note For configuring multiple monitors automatically see https://github.com/polybar/polybar/issues/763

[bar/mybar]
; Use either of the following command to list available outputs:
; If unspecified, the application will pick the first one it finds.
; $ polybar -m | cut -d ':' -f 1
; $ xrandr -q | grep " connected" | cut -d ' ' -f1
monitor =

; Use the specified monitor as a fallback if the main one is not found.
monitor-fallback =

; Require the monitor to be in connected state
; XRandR sometimes reports my monitor as being disconnected (when in use)
monitor-strict = false

; Tell the Window Manager not to configure the window.
; Use this to detach the bar if your WM is locking its size/position.
override-redirect = false

; Put the bar at the bottom of the screen
bottom = false

; Prefer fixed center position for the `modules-center` block
; When false, the center position will be based on the size of the other blocks.
fixed-center = true

; Dimension defined as pixel value (e.g. 35) or percentage (e.g. 50%),
; the percentage can optionally be extended with a pixel offset like so:
; 50%:-10, this will result in a width or height of 50% minus 10 pixels
width =
height =

; Offset defined as pixel value (e.g. 35) or percentage (e.g. 50%)
; the percentage can optionally be extended with a pixel offset like so:
; 50%:-10, this will result in an offset in the x or y direction 
; of 50% minus 10 pixels
offset-x = 0
offset-y = 0

; Background ARGB color (e.g. #f00, #ff992a, #ddff1023)
background = #fff

; Foreground ARGB color (e.g. #f00, #ff992a, #ddff1023)
foreground = #000

; Background gradient (vertical steps)
;   background-[0-9]+ = #aarrggbb
background-0 = 

; Value used for drawing rounded corners
; Note: This shouldn't be used together with border-size because the border 
; doesn't get rounded. For this to work you may also need to enable 
; pseudo-transparency or use a compositor like compton.
; Individual top/bottom values can be defined using:
;   radius-{top,bottom}
radius = 0.0

; Under-/overline pixel size and argb color
; Individual values can be defined using:
;   {overline,underline}-size
;   {overline,underline}-color
line-size = 1
line-color = #f00

; Values applied to all borders
; Individual side values can be defined using:
;   border-{left,top,right,bottom}-size
;   border-{left,top,right,bottom}-color
; The top and bottom borders are added to the bar height, so the effective
; window height is:
;   height + border-top-size + border-bottom-size
; Meanwhile the effective window width is defined entirely by the width key and
; the border is placed withing this area. So you effectively only have the
; following horizontal space on the bar:
;   width - border-right-size - border-left-size
border-size =
border-color =

; Number of spaces to add at the beginning/end of the bar
; Individual side values can be defined using:
;   padding-{left,right}
padding = 0

; Number of spaces to add before/after each module
; Individual side values can be defined using:
;   module-margin-{left,right}
module-margin = 0

; Fonts are defined using <font-name>;<vertical-offset>
; Font names are specified using a fontconfig pattern.
;   font-0 = NotoSans-Regular:size=8;2
;   font-1 = MaterialIcons:size=10
;   font-2 = Termsynu:size=8;-1
;   font-3 = FontAwesome:size=10
; See the Fonts wiki page for more details
font-0 =

; Modules are added to one of the available blocks
;   modules-left = cpu ram
;   modules-center = xwindow xbacklight
;   modules-right = ipc clock
modules-left =
modules-center =
modules-right =

; The separator will be inserted between the output of each module
separator =

; This value is used to add extra spacing between elements
; @deprecated: This parameter will be removed in an upcoming version
spacing = 0

; Opacity value between 0.0 and 1.0 used on fade in/out
dim-value = 1.0

; Value to be used to set the WM_NAME atom
; If the value is empty or undefined, the atom value
; will be created from the following template: polybar-[BAR]_[MONITOR]
; NOTE: The placeholders are not available for custom values
wm-name =

; Locale used to localize various module data (e.g. date)
; Expects a valid libc locale, for example: sv_SE.UTF-8
locale = 

; Position of the system tray window
; If empty or undefined, tray support will be disabled
; NOTE: A center aligned tray will cover center aligned modules
;
; Available positions:
;   left
;   center
;   right
;   none
tray-position =

; If true, the bar will not shift its
; contents when the tray changes
tray-detached = false

; Tray icon max size
tray-maxsize = 16

; DEPRECATED! Since 3.3.0 the tray always uses pseudo-transparency
; Enable pseudo transparency
; Will automatically be enabled if a fully transparent
; background color is defined using `tray-background`
tray-transparent = false

; Background color for the tray container 
; ARGB color (e.g. #f00, #ff992a, #ddff1023)
; By default the tray container will use the bar
; background color.
tray-background = ${root.background}

; Tray offset defined as pixel value (e.g. 35) or percentage (e.g. 50%)
tray-offset-x = 0
tray-offset-y = 0

; Pad the sides of each tray icon
tray-padding = 0

; Scale factor for tray clients
tray-scale = 1.0

; Restack the bar window and put it above the
; selected window manager's root
;
; Fixes the issue where the bar is being drawn
; on top of fullscreen window's
;
; Currently supported WM's:
;   bspwm
;   i3 (requires: `override-redirect = true`)
; wm-restack =

; Set a DPI values used when rendering text
; This only affects scalable fonts
; Set this to 0 to let polybar calculate the dpi from the screen size.
; dpi = 
dpi-x = 96
dpi-y = 96

; Enable support for inter-process messaging
; See the Messaging wiki page for more details.
enable-ipc = false

; Fallback click handlers that will be called if
; there's no matching module handler found.
click-left = 
click-middle = 
click-right =
scroll-up =
scroll-down =
double-click-left =
double-click-middle =
double-click-right =

; Requires polybar to be built with xcursor support (xcb-util-cursor)
; Possible values are:
; - default   : The default pointer as before, can also be an empty string (default)
; - pointer   : Typically in the form of a hand
; - ns-resize : Up and down arrows, can be used to indicate scrolling
cursor-click = 
cursor-scroll = 

Global WM settings

[global/wm]
; Adjust the _NET_WM_STRUT_PARTIAL top value
;   Used for top aligned bars
margin-bottom = 0

; Adjust the _NET_WM_STRUT_PARTIAL bottom value
;   Used for bottom aligned bars
margin-top = 0

Application settings

[settings]
; The throttle settings lets the eventloop swallow up til X events
; if they happen within Y millisecond after first event was received.
; This is done to prevent flood of update event.
;
; For example if 5 modules emit an update event at the same time, we really
; just care about the last one. But if we wait too long for events to swallow
; the bar would appear sluggish so we continue if timeout
; expires or limit is reached.
throttle-output = 5
throttle-output-for = 10

; Time in milliseconds that the input handler will wait between processing events
throttle-input-for = 30

; Reload upon receiving XCB_RANDR_SCREEN_CHANGE_NOTIFY events
screenchange-reload = false

; Compositing operators
; @see: https://www.cairographics.org/manual/cairo-cairo-t.html#cairo-operator-t
compositing-background = source
compositing-foreground = over
compositing-overline = over
compositing-underline = over
compositing-border = over

; Define fallback values used by all module formats
format-foreground = 
format-background = 
format-underline =
format-overline =
format-spacing =
format-padding =
format-margin =
format-offset =

; Enables pseudo-transparency for the bar
; If set to true the bar can be transparent without a compositor.
pseudo-transparency = false
You can’t perform that action at this time.