A flexible scheduler for your i3bar blocks
C Shell Perl Makefile
Clone or download
Latest commit 403308b Jan 6, 2018
Zopieux authored and vivien committed Jan 6, 2018 README: promote contrib scripts
Closes #178 #282



Build Status Join the chat at https://gitter.im/vivien/i3blocks

i3blocks is a highly flexible status line for the i3 window manager. It handles clicks, signals and language-agnostic user scripts.

The content of each block (e.g. time, battery status, network state, ...) is the output of a command provided by the user. Blocks are updated on click, at a given interval of time or on a given signal, also specified by the user.

It aims to respect the i3bar protocol, providing customization such as text alignment, urgency, color, and more.

Here is an example of status line, showing the time updated every 5 seconds, the volume updated only when i3blocks receives a SIGRTMIN+1, and click events.

command=amixer get Master | grep -E -o '[0-9]{1,3}?%' | head -1
# use 'pkill -RTMIN+1 i3blocks' after changing the volume

command=date '+%D %T'

full_text=Click me!
command=echo button=$BLOCK_BUTTON x=$BLOCK_X y=$BLOCK_Y
min_width=button=1 x=1366 y=768

You can use your own scripts, or the ones provided with i3blocks. Many community-contributed scripts are also available. Feel free to contribute and improve them!

The default config will look like this:

The scripts provided by default may use external tools:

  • mpstat (often provided by the sysstat package) used by cpu_usage.
  • acpi (often provided by a package of the same name) used by battery.

The user contributed scripts may also use external tools:

  • playerctl (available here) used by mediaplayer.
  • sensors (often provided by the lm-sensors package) used by temperature.


For more information about how it works, please refer to the manpage.

You can also take a look at the i3bar protocol to see what possibilities it offers you.

Take a look at the wiki for examples of blocks and screenshots. If you want to share your ideas and status line, feel free to edit it!


i3blocks may already be packaged for your distribution:

Or you may install i3blocks from source:

$ git clone git://github.com/vivien/i3blocks
$ cd i3blocks
$ make clean debug # or make clean all
# make install

Note: the generation of the manpage requires the pandoc utility, packaged in common distributions as pandoc.


  • Set your status_command in a bar block of your i3 config file:

    bar {
      status_command i3blocks
  • For customization, copy the default i3blocks.conf into ~/.i3blocks.conf (e.g. cp /etc/i3blocks.conf ~/.i3blocks.conf)

  • Restart i3 (e.g. i3-msg restart)


i3blocks is Copyright (C) 2014 Vivien Didelot
See the file COPYING for information of licensing and distribution.