git.sur5r.net Git - i3/i3.github.io/blob - docs/user-contributed/py3status.html

   1 ---
   2 layout: default
   3 title: Docs
   4 group: Docs
   5 ---
   6 <div id="content" class="usergen">
   7 <h1>User-contributed article: enhanced and extensible i3bar with py3status</h1>
   8
   9 <p>
  10 In the i3 documentation, the recommended tool for <a
  11 href="http://i3wm.org/docs/userguide.html#_displaying_a_status_line">displaying
  12 a status line is to use i3status</a> combined with i3bar.
  13 </p>
  14
  15 <p>
  16 While i3status is very efficient at what it does, it is by design limited to
  17 a few modules and does not allow you to inject your own scripts output on your
  18 i3bar. This is said pretty clearly on the i3status man page:
  19 </p>
  20
  21 <pre><tt>In i3status, we don’t want to implement process management again.
  22 Therefore, there is no module to run arbitrary scripts or commands.
  23 Instead, you should use your shell.</tt></pre>
  24
  25 <h2>Introducing py3status</h2>
  26
  27 <p>
  28 The goal of py3status is to fill this gap by allowing users to simply extend
  29 their i3bar while preserving their current i3status configuration. The main idea
  30 is to rely on i3status' strengths without adding any configuration on the user's
  31 side. py3status is thus a wrapper script for i3status and you can
  32 <a href="https://github.com/ultrabug/py3status/wiki"> read more on the wiki</a>.
  33 </p>
  34
  35 <h2>Requirements</h2>
  36
  37 <p>
  38 To achieve this, py3status uses the <a
  39 href="http://i3wm.org/docs/i3bar-protocol.html">i3bar protocol</a> so your
  40 i3status.conf should specify this as its output_format.
  41 </p>
  42
  43 <pre><tt>general {
  44     output_format = "i3bar"
  45 }</tt></pre>
  46
  47 <h2>Usage</h2>
  48
  49 <p>
  50 Using py3status is easy, no need to multi-pipe your scripts after i3status.
  51 Instead, just replace i3status in your current status_command by py3status.
  52 For example, if you're using your own i3status.conf, you need to change your
  53 i3 config file with:
  54 </p>
  55
  56 <pre><tt>status_command py3status -c ~/.i3/i3status.conf</tt></pre>
  57
  58 <h2>Display your own stuff</h2>
  59
  60 <p>
  61 py3status features a simple and straightforward plugin system which you can use
  62 to get your own output displayed on your i3bar. You can read more and view some
  63 examples <a
  64 href="https://github.com/ultrabug/py3status/wiki/Write-your-own-modules"> on the
  65 wiki</a>.
  66 </p>
  67
  68 <h2>Documentation</h2>
  69
  70 <p>
  71 You can read the full and up to date documentation on the <a
  72 href="https://github.com/ultrabug/py3status">py3status home page</a>.
  73 </p>