Skip to content

Module: script

patrick96 edited this page Feb 6, 2020 · 34 revisions

This module executes the defined script and displays its output. You can find community-curated script modules in the polybar-scripts repository.

The module will wait for the exec script to finish until updating its contents. If you are launching an application, make sure you are sending it to the background by appending & after the line that executes the application. The same goes for the click-* commands.
If your script is using an infinite loop in combination with tail = true, the exec-if condition is only checked until it evaluates to true for the first time, because it is only checked before running the exec command and since the exec command never returns (because of the infinite loop), exec-if is never evaluated again, once the exec command is running. So if the exec-if condition at some point, while the infinite loop is running, would evaluate to false the script will not suddenly stop running and the module will not disappear.

If you want that your module disappear from the bar in some cases, your output has to be created with echo "" Otherwise an outdated output is still on the bar. See #504.

Basic settings

type = custom/script

; Available tokens:
;   %counter%
; Command to be executed (using "/bin/sh -c [command]")
exec = checkforupdates

; Conditional command that, if defined, needs to exit successfully
; before the main exec command is invoked.
; Default: ""
exec-if = pgrep -x myservice

; Will the script output continous content?
; Default: false
tail = true

; Seconds to sleep between updates
; Default: 5 (0 if `tail = true`)
interval = 90

Additional formatting

; Available tags:
;   <output> - deprecated
;   <label> (default)
format = <label>
format-background = #999
format-foreground = #000
format-padding = 4

; Available tokens:
;   %output%
; Default: %output%
label = %output:0:15:...%

; Available tokens:
;   %counter%
;   %pid%
; "click-(left|middle|right)" will be executed using "/bin/sh -c [command]"
click-left = echo left %counter%
click-middle = echo middle %counter%
click-right = echo right %counter%
double-click-left = echo double left %counter%
double-click-middle = echo double middle %counter%
double-click-right = echo double right %counter%

; Available tokens:
;   %counter%
;   %pid%
; "scroll-(up|down)" will be executed using "/bin/sh -c [command]"
scroll-up = echo scroll up %counter%
scroll-down = echo scroll down %counter%


You can use exec-if to only display output once the defined condition is met. For example:

type = custom/script
exec = echo vpn
exec-if = pgrep -x openvpn
interval = 5
format-underline = #268bd2
format-prefix = "🖧 "
format-prefix-foreground = #5b

The %pid% token can be used to send signals to the script, allowing for multiple states. Here is an example of a date script with two states:

type = custom/script
exec = /path/to/
tail = true
click-left = kill -USR1 %pid%

Note: %pid% actually refers to the sh process that executes the exec command. The shell will generally relay signals to the exec command. However if the command runs in the background it won't. In those cases you can use pgrep to find the oldest child belonging to %pid% and send the signal to that (child) pid:

click-left = "kill -USR1 $(pgrep --oldest --parent %pid%)"


toggle() {
    t=$(((t + 1) % 2))

trap "toggle" USR1

while true; do
    if [ $t -eq 0 ]; then
        date --rfc-3339=seconds
    sleep 1 &
You can’t perform that action at this time.