1I3STATUS(1) i3 Manual I3STATUS(1)
2
6 i3status - Generates a status line for i3bar, dzen2, xmobar or lemonbar
7
9 i3status [-c configfile] [-h] [-v]
10
12 -c
13 Specifies an alternate configuration file path. By default,
14 i3status looks for configuration files in the following order:
15 1. ~/.config/i3status/config (or $XDG_CONFIG_HOME/i3status/config
17 if set)
18 2. /etc/xdg/i3status/config (or $XDG_CONFIG_DIRS/i3status/config
20 if set)
21 3. ~/.i3status.conf
23 4. /etc/i3status.conf
25
27 i3status is a small program (about 1500 SLOC) for generating a status
28 bar for i3bar, dzen2, xmobar, lemonbar or similar programs. It is
29 designed to be very efficient by issuing a very small number of system
30 calls, as one generally wants to update such a status line every
31 second. This ensures that even under high load, your status bar is
32 updated correctly. Also, it saves a bit of energy by not hogging your
33 CPU as much as spawning the corresponding amount of shell commands
34 would.
35
37 The basic idea of i3status is that you can specify which "modules"
38 should be used (the order directive). You can then configure each
39 module with its own section. For every module, you can specify the
40 output format. See below for a complete reference.
41 Sample configuration.
43 general {
45 output_format = "dzen2"
46 colors = true
47 interval = 5
48 }
49 order += "ipv6"
51 order += "disk /"
52 order += "run_watch DHCP"
53 order += "run_watch VPNC"
54 order += "path_exists VPN"
55 order += "wireless wlan0"
56 order += "ethernet eth0"
57 order += "battery 0"
58 order += "cpu_temperature 0"
59 order += "load"
60 order += "tztime local"
61 order += "tztime berlin"
62 wireless wlan0 {
64 format_up = "W: (%quality at %essid, %bitrate) %ip"
65 format_down = "W: down"
66 }
67 ethernet eth0 {
69 # if you use %speed, i3status requires the cap_net_admin capability
70 format_up = "E: %ip (%speed)"
71 format_down = "E: down"
72 }
73 battery 0 {
75 format = "%status %percentage %remaining %emptytime"
76 format_down = "No battery"
77 status_chr = "⚡ CHR"
78 status_bat = "🔋 BAT"
79 status_unk = "? UNK"
80 status_full = "☻ FULL"
81 path = "/sys/class/power_supply/BAT%d/uevent"
82 low_threshold = 10
83 }
84 run_watch DHCP {
86 pidfile = "/var/run/dhclient*.pid"
87 }
88 run_watch VPNC {
90 # file containing the PID of a vpnc process
91 pidfile = "/var/run/vpnc/pid"
92 }
93 path_exists VPN {
95 # path exists when a VPN tunnel launched by nmcli/nm-applet is active
96 path = "/proc/sys/net/ipv4/conf/tun0"
97 }
98 tztime local {
100 format = "%Y-%m-%d %H:%M:%S"
101 }
102 tztime berlin {
104 format = "%Y-%m-%d %H:%M:%S %Z"
105 timezone = "Europe/Berlin"
106 }
107 load {
109 format = "%5min"
110 }
111 cpu_temperature 0 {
113 format = "T: %degrees °C"
114 path = "/sys/devices/platform/coretemp.0/temp1_input"
115 }
116 disk "/" {
118 format = "%free"
119 }
120 General
123 The colors directive will disable all colors if you set it to false.
124 You can also specify the colors that will be used to display "good",
125 "degraded" or "bad" values using the color_good, color_degraded or
126 color_bad directives, respectively. Those directives are only used if
127 color support is not disabled by the colors directive. The input format
128 for color values is the canonical RGB hexadecimal triplet (with no
129 separators between the colors), prefixed by a hash character ("#").
130 Example configuration:
132 color_good = "#00FF00"
134 Likewise, you can use the color_separator directive to specify the
136 color that will be used to paint the separator bar. The separator is
137 always output in color, even when colors are disabled by the colors
138 directive. This option has no effect when output_format is set to i3bar
139 or none.
140 The interval directive specifies the time in seconds for which i3status
142 will sleep before printing the next status line.
143 Using output_format you can chose which format strings i3status should
145 use in its output. Currently available are:
146 i3bar
148 i3bar comes with i3 and provides a workspace bar which does the
149 right thing in multi-monitor situations. It also comes with tray
150 support and can display the i3status output. This output type uses
151 JSON to pass as much meta-information to i3bar as possible (like
152 colors, which blocks can be shortened in which way, etc.).
153 dzen2
155 Dzen is a general purpose messaging, notification and menuing
156 program for X11. It was designed to be scriptable in any language
157 and integrate well with window managers like dwm, wmii and xmonad
158 though it will work with any windowmanger
159 xmobar
161 xmobar is a minimalistic, text based, status bar. It was designed
162 to work with the xmonad Window Manager.
163 lemonbar
165 lemonbar is a lightweight bar based entirely on XCB. It has full
166 UTF-8 support and is EWMH compliant.
167 term
169 Use ANSI Escape sequences to produce a terminal-output as close as
170 possible to the graphical outputs. This makes debugging your config
171 file a little bit easier because the terminal-output of i3status
172 becomes much more readable, but should only used for such quick
173 glances, because it will only support very basic output-features
174 (for example you only get 3 bits of color depth).
175 none
177 Does not use any color codes. Separates values by the pipe symbol
178 by default. This should be used with i3bar and can be used for
179 custom scripts.
180 It’s also possible to use the color_good, color_degraded, color_bad
182 directives to define specific colors per module. If one of these
183 directives is defined in a module section its value will override the
184 value defined in the general section just for this module.
185 If you don’t fancy the vertical separators between modules
187 i3status/i3bar uses by default, you can employ the separator directive
188 to configure how modules are separated. You can either disable the
189 default separator altogether setting it to the empty string. You might
190 then define separation as part of a module’s format string. This is
191 your only option when using the i3bar output format as the separator is
192 drawn by i3bar directly otherwise. For the other output formats, the
193 provided non-empty string will be automatically enclosed with the
194 necessary coloring bits if color support is enabled.
195 i3bar supports Pango markup, allowing your format strings to specify
197 font color, size, etc. by setting the markup directive to "pango". Note
198 that the ampersand ("&"), less-than ("<"), greater-than (">"),
199 single-quote ("'"), and double-quote (""") characters need to be
200 replaced with "&", "<", ">", "'", and """
201 respectively. This is done automatically for generated content (e.g.
202 wireless ESSID, time).
203 Example configuration:
205 general {
207 output_format = "xmobar"
208 separator = " "
209 }
210 order += "load"
212 order += "disk /"
213 load {
215 format = "[ load: %1min, %5min, %15min ]"
216 }
217 disk "/" {
218 format = "%avail"
219 }
220 IPv6
222 This module gets the IPv6 address used for outgoing connections (that
223 is, the best available public IPv6 address on your computer).
224 Example format_up: %ip
226 Example format_down: no IPv6
228 Disk
230 Gets used, free, available and total amount of bytes on the given
231 mounted filesystem.
232 These values can also be expressed in percentages with the
234 percentage_used, percentage_free, percentage_avail and
235 percentage_used_of_avail formats.
236 Byte sizes are presented in a human readable format using a set of
238 prefixes whose type can be specified via the "prefix_type" option.
239 Three sets of prefixes are available:
240 binary
242 IEC prefixes (Ki, Mi, Gi, Ti) represent multiples of powers of
243 1024. This is the default.
244 decimal
246 SI prefixes (k, M, G, T) represent multiples of powers of 1000.
247 custom
249 The custom prefixes (K, M, G, T) represent multiples of powers of
250 1024.
251 It is possible to define a low_threshold that causes the disk text to
253 be displayed using color_bad. The low_threshold type can be of
254 threshold_type "bytes_free", "bytes_avail", "percentage_free", or
255 "percentage_avail", where the former two can be prepended by a generic
256 prefix (k, m, g, t) having prefix_type. So, if you configure
257 low_threshold to 2, threshold_type to "gbytes_avail", and prefix_type
258 to "binary", and the remaining available disk space is below 2 GiB, it
259 will be colored bad. If not specified, threshold_type is assumed to be
260 "percentage_avail" and low_threshold to be set to 0, which implies no
261 coloring at all. You can customize the output format when below
262 low_threshold with format_below_threshold.
263 You can define a different format with the option "format_not_mounted"
265 which is used if the path does not exist or is not a mount point.
266 Defaults to "".
267 Example order: disk /mnt/usbstick
269 Example format: %free (%avail)/ %total
271 Example format: %percentage_used used, %percentage_free free,
273 %percentage_avail avail
274 Example prefix_type: custom
276 Example low_threshold: 5
278 Example format_below_threshold: Warning: %percentage_avail
280 Example threshold_type: percentage_free
282 Run-watch
284 Expands the given path to a pidfile and checks if the process ID found
285 inside is valid (that is, if the process is running). You can use this
286 to check if a specific application, such as a VPN client or your DHCP
287 client is running. There also is an option "format_down". You can hide
288 the output with format_down="".
289 Example order: run_watch DHCP
291 Example format: %title: %status
293 Path-exists
295 Checks if the given path exists in the filesystem. You can use this to
296 check if something is active, like for example a VPN tunnel managed by
297 NetworkManager. There also is an option "format_down". You can hide the
298 output with format_down="".
299 Example order: path_exists VPN
301 Example format: %title: %status
303 Wireless
305 Gets the link quality, frequency and ESSID of the given wireless
306 network interface. You can specify different format strings for the
307 network being connected or not connected.
308 The special interface name _first_ will be replaced by the first
310 wireless network interface found on the system (excluding devices
311 starting with "lo").
312 Example order: wireless wlan0
314 Example format: W: (%quality at %essid, %bitrate / %frequency) %ip
316 Ethernet
318 Gets the IP address and (if possible) the link speed of the given
319 ethernet interface. Getting the link speed requires the cap_net_admin
320 capability. Set it using setcap cap_net_admin=ep $(which i3status).
321 The special interface name _first_ will be replaced by the first
323 non-wireless network interface found on the system (excluding devices
324 starting with "lo").
325 Example order: ethernet eth0
327 Example format: E: %ip (%speed)
329 Battery
331 Gets the status (charging, discharging, unknown, full), percentage,
332 remaining time and power consumption (in Watts) of the given battery
333 and when it’s estimated to be empty. If you want to use the last full
334 capacity instead of the design capacity (when using the design
335 capacity, it may happen that your battery is at 23% when fully charged
336 because it’s old. In general, I want to see it this way, because it
337 tells me how worn off my battery is.), just specify last_full_capacity
338 = true. You can hide seconds in the remaining time and empty time
339 estimations by setting hide_seconds = true.
340 If you want the battery percentage to be shown without decimals, add
342 integer_battery_capacity = true.
343 If your battery is represented in a non-standard path in /sys, be sure
345 to modify the "path" property accordingly, i.e. pointing to the uevent
346 file on your system. The first occurrence of %d gets replaced with the
347 battery number, but you can just hard-code a path as well.
348 It is possible to define a low_threshold that causes the battery text
350 to be colored red. The low_threshold type can be of threshold_type
351 "time" or "percentage". So, if you configure low_threshold to 10 and
352 threshold_type to "time", and your battery lasts another 9 minutes, it
353 will be colored red.
354 To show an aggregate of all batteries in the system, use "all" as the
356 number. In this case (for Linux), the /sys path must contain the "%d"
357 sequence. Otherwise, the number indicates the battery index as reported
358 in /sys.
359 Optionally custom strings including any UTF-8 symbols can be used for
361 different battery states. This makes it possible to display individual
362 symbols for each state (charging, discharging, unknown, full) Of course
363 it will also work with special iconic fonts, such as FontAwesome. If
364 any of these special status strings are omitted, the default (CHR, BAT,
365 UNK, FULL) is used.
366 Example order (for the first battery): battery 0
368 Example order (aggregate of all batteries): battery all
370 Example format: %status %remaining (%emptytime %consumption)
372 Example format_down: No battery
374 Example status_chr: ⚡ CHR
376 Example status_bat: 🔋 BAT
378 Example status_unk: ? UNK
380 Example status_full: ☻ FULL
382 Example low_threshold: 30
384 Example threshold_type: time
386 Example path (%d replaced by title number):
388 /sys/class/power_supply/CMB%d/uevent
389 Example path (ignoring the number): /sys/class/power_supply/CMB1/uevent
391 CPU-Temperature
393 Gets the temperature of the given thermal zone. It is possible to
394 define a max_threshold that will color the temperature red in case the
395 specified thermal zone is getting too hot. Defaults to 75 degrees C.
396 The output format when above max_threshold can be customized with
397 format_above_threshold.
398 Example order: cpu_temperature 0
400 Example format: T: %degrees °C
402 Example max_threshold: 42
404 Example format_above_threshold: Warning T above threshold: %degrees °C
406 Example path: /sys/devices/platform/coretemp.0/temp1_input
408 CPU Usage
410 Gets the percentual CPU usage from /proc/stat (Linux) or sysctl(3)
411 (FreeBSD/OpenBSD).
412 It is possible to define a max_threshold that will color the load value
414 red in case the CPU average over the last interval is getting higher
415 than the configured threshold. Defaults to 95. The output format when
416 above max_threshold can be customized with format_above_threshold.
417 It is possible to define a degraded_threshold that will color the load
419 value yellow in case the CPU average over the last interval is getting
420 higher than the configured threshold. Defaults to 90. The output format
421 when above degraded threshold can be customized with
422 format_above_degraded_threshold.
423 Example order: cpu_usage
425 Example format: %usage
427 Example max_threshold: 75
429 Example format_above_threshold: Warning above threshold: %usage
431 Example degraded_threshold: 25
433 Example format_above_degraded_threshold: Warning above degraded
435 threshold: %usage
436 Load
438 Gets the system load (number of processes waiting for CPU time in the
439 last 1, 5 and 15 minutes). It is possible to define a max_threshold
440 that will color the load value red in case the load average of the last
441 minute is getting higher than the configured threshold. Defaults to 5.
442 The output format when above max_threshold can be customized with
443 format_above_threshold.
444 Example order: load
446 Example format: %1min %5min %15min
448 Example max_threshold: "0,1"
450 Example format_above_threshold: Warning: %1min %5min %15min
452 Time
454 Outputs the current time in the local timezone. To use a different
455 timezone, you can set the TZ environment variable, or use the tztime
456 module. See strftime(3) for details on the format string.
457 Example order: time
459 Example format: %Y-%m-%d %H:%M:%S
461 TzTime
463 Outputs the current time in the given timezone. If no timezone is
464 given, local time will be used. See strftime(3) for details on the
465 format string. The system’s timezone database is usually installed in
466 /usr/share/zoneinfo. Files below that path make for valid timezone
467 strings, e.g. for /usr/share/zoneinfo/Europe/Berlin you can set
468 timezone to Europe/Berlin in the tztime module. To override the locale
469 settings of your environment, set the locale option.
470 Example order: tztime berlin
472 Example format: %Y-%m-%d %H:%M:%S %Z
474 Example timezone: Europe/Berlin
476 Example locale: de_DE.UTF-8
478 If you would like to use markup in this section, there is a separate
480 format_time option that is automatically escaped. Its output then
481 replaces %time in the format string.
482 Example configuration (markup):
484 tztime berlin {
486 format = "<span foreground='#ffffff'>time:</span> %time"
487 format_time = "%H:%M %Z"
488 timezone = "Europe/Berlin"
489 }
490 DDate
492 Outputs the current discordian date in user-specified format. See
493 ddate(1) for details on the format string. Note: Neither %. nor %X are
494 implemented yet.
495 Example order: ddate
497 Example format: %{%a, %b %d%}, %Y%N - %H
499 Volume
501 Outputs the volume of the specified mixer on the specified device.
502 PulseAudio and ALSA (Linux only) are supported. If PulseAudio is
503 absent, a simplified configuration can be used on FreeBSD and OpenBSD
504 due to the lack of ALSA, the device and mixer options can be ignored on
505 these systems. On these systems the OSS API is used instead to query
506 /dev/mixer directly if mixer_idx is -1, otherwise
507 /dev/mixer+mixer_idx+.
508 To get PulseAudio volume information, one must use the following format
510 in the device line:
511 device = "pulse"
513 or
515 device = "pulse:N"
517 where N is the index or name of the PulseAudio sink. You can obtain the
519 name of the sink with the following command:
520 $ pacmd list-sinks | grep name:
522 name: <alsa_output.pci-0000_00_14.2.analog-stereo>
523 The name is what’s inside the angle brackets, not including them. If no
525 sink is specified the default sink is used. If the device string is
526 missing or is set to "default", PulseAudio will be tried if detected
527 and will fallback to ALSA (Linux) or OSS (FreeBSD/OpenBSD).
528 Example order: volume master
530 Example format: ♪: %volume
532 Example format_muted: ♪: 0%%
534 Example configuration:
536 volume master {
538 format = "♪: %volume"
539 format_muted = "♪: muted (%volume)"
540 device = "default"
541 mixer = "Master"
542 mixer_idx = 0
543 }
544 Example configuration (PulseAudio):
546 volume master {
548 format = "♪: %volume"
549 format_muted = "♪: muted (%volume)"
550 device = "pulse:1"
551 }
552 volume master {
554 format = "♪: %volume"
555 format_muted = "♪: muted (%volume)"
556 device = "pulse:alsa_output.pci-0000_00_14.2.analog-stereo"
557 }
558
560 When using the i3bar output format, there are a few additional options
561 that can be used with all modules to customize their appearance:
562 align
564 The alignment policy to use when the minimum width (see below) is
565 not reached. Either center (default), right or left.
566 min_width
568 The minimum width (in pixels) the module should occupy. If the
569 module takes less space than the specified size, the block will be
570 padded to the left and/or the right side, according to the defined
571 alignment policy. This is useful when you want to prevent the whole
572 status line from shifting when values take more or less space
573 between each iteration. The option can also be a string. In this
574 case, the width of the given text determines the minimum width of
575 the block. This is useful when you want to set a sensible minimum
576 width regardless of which font you are using, and at what
577 particular size. Please note that a number enclosed with quotes
578 will still be treated as a number.
579 separator
581 A boolean value which specifies whether a separator line should be
582 drawn after this block. The default is true, meaning the separator
583 line will be drawn. Note that if you disable the separator line,
584 there will still be a gap after the block, unless you also use
585 separator_block_width.
586 separator_block_width
588 The amount of pixels to leave blank after the block. In the middle
589 of this gap, a separator symbol will be drawn unless separator is
590 disabled. This is why the specified width should leave enough space
591 for the separator symbol.
592 Example configuration:
594 disk "/" {
596 format = "%avail"
597 align = "left"
598 min_width = 100
599 separator = false
600 separator_block_width = 1
601 }
602
604 After installing dzen2, you can directly use it with i3status. Just
605 ensure that output_format is set to dzen2.
606 Example for usage of i3status with dzen2:
608 i3status | dzen2 -fg white -ta r -w 1280 \
610 -fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"
611
613 To get xmobar to start, you might need to copy the default
614 configuration file to ~/.xmobarrc. Also, ensure that the output_format
615 option for i3status is set to xmobar.
616 Example for usage of i3status with xmobar:
618 i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"
620
622 While talking about two specific things, please understand this section
623 as a general explanation why your favorite information is not included
624 in i3status.
625 Let’s talk about memory usage specifically. It is hard to measure
627 memory in a way which is accurate or meaningful. An in-depth
628 understanding of how paging and virtual memory work in your operating
629 system is required. Furthermore, even if we had a well-defined way of
630 displaying memory usage and you would understand it, I think that it’s
631 not helpful to repeatedly monitor your memory usage. One reason for
632 that is that I have not run out of memory in the last few years. Memory
633 has become so cheap that even in my 4 year old notebook, I have 8 GiB
634 of RAM. Another reason is that your operating system will do the right
635 thing anyway: Either you have not enough RAM for your workload, but you
636 need to do it anyway, then your operating system will swap. Or you
637 don’t have enough RAM and you want to restrict your workload so that it
638 fits, then the operating system will kill the process using too much
639 RAM and you can act accordingly.
640 For CPU frequency, the situation is similar. Many people don’t
642 understand how frequency scaling works precisely. The generally
643 recommended CPU frequency governor ("ondemand") changes the CPU
644 frequency far more often than i3status could display it. The display
645 number is therefore often incorrect and doesn’t tell you anything
646 useful either.
647 In general, i3status wants to display things which you would look at
649 occasionally anyways, like the current date/time, whether you are
650 connected to a WiFi network or not, and if you have enough disk space
651 to fit that 4.3 GiB download.
652 However, if you need to look at some kind of information more than once
654 in a while (like checking repeatedly how full your RAM is), you are
655 probably better off with a script doing that, which pops up an alert
656 when your RAM usage reaches a certain threshold. After all, the point
657 of computers is not to burden you with additional boring tasks like
658 repeatedly checking a number.
659
661 In i3status, we don’t want to implement process management again.
662 Therefore, there is no module to run arbitrary scripts or commands.
663 Instead, you should use your shell, for example like this:
664 Example for prepending the i3status output:
666 #!/bin/sh
668 # shell script to prepend i3status with more stuff
669 i3status | while :
671 do
672 read line
673 echo "mystuff | $line" || exit 1
674 done
675 Put that in some script, say .bin/my_i3status.sh and execute that
677 instead of i3status.
678 Note that if you want to use the JSON output format (with colors in
680 i3bar), you need to use a slightly more complex wrapper script. There
681 are examples in the contrib/ folder, see
682 https://github.com/i3/i3status/tree/master/contrib
683
685 When receiving SIGUSR1, i3status’s nanosleep() will be interrupted and
686 thus you will force an update. You can use killall -USR1 i3status to
687 force an update after changing the system volume, for example.
688
690 strftime(3), date(1), glob(3), dzen2(1), xmobar(1)
691
693 Michael Stapelberg and contributors
694 Thorsten Toepper
696 Baptiste Daroussin
698 Axel Wagner
700 Fernando Tarlá Cardoso Lemos
702i3status v2.11 01/21/2017 I3STATUS(1)