i3 - improved tiling WM

User-contributed article: enhanced and extensible i3bar with py3status

In the i3 documentation, the recommended tool for displaying a status line is to use i3status combined with i3bar.

While i3status is very efficient at what it does, it is by design limited to a few modules and does not allow you to inject your own scripts output on your i3bar. This is said pretty clearly on the i3status man page:

In i3status, we don’t want to implement process management again.
Therefore, there is no module to run arbitrary scripts or commands.
Instead, you should use your shell.

Introducing py3status

The goal of py3status is to fill this gap by allowing users to simply extend their i3bar while preserving their current i3status configuration. The main idea is to rely on i3status' strengths without adding any configuration on the user's side. py3status is thus a wrapper script for i3status and you can read more on the wiki.


To achieve this, py3status uses the i3bar protocol so your i3status.conf should specify this as its output_format.

general {
    output_format = "i3bar"


Using py3status is easy, no need to multi-pipe your scripts after i3status. Instead, just replace i3status in your current status_command by py3status. For example, if you're using your own i3status.conf, you need to change your i3 config file with:

status_command py3status -c ~/.i3/i3status.conf

Display your own stuff

py3status features a simple and straightforward plugin system which you can use to get your own output displayed on your i3bar. You can read more and view some examples on the wiki.


You can read the full and up to date documentation on the py3status home page.