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 for generating a status bar for i3bar,
28 dzen2, xmobar, lemonbar or similar programs. It is designed to be very
29 efficient by issuing a very small number of system calls, as one
30 generally wants to update such a status line every second. This ensures
31 that even under high load, your status bar is updated correctly. Also,
32 it saves a bit of energy by not hogging your CPU as much as spawning
33 the corresponding amount of shell commands would.
34
36 The basic idea of i3status is that you can specify which "modules"
37 should be used (the order directive). You can then configure each
38 module with its own section. For every module, you can specify the
39 output format. See below for a complete reference.
40 Sample configuration.
42 general {
44 output_format = "dzen2"
45 colors = true
46 interval = 5
47 }
48 order += "ipv6"
50 order += "disk /"
51 order += "run_watch DHCP"
52 order += "run_watch VPNC"
53 order += "path_exists VPN"
54 order += "wireless wlan0"
55 order += "ethernet eth0"
56 order += "battery 0"
57 order += "cpu_temperature 0"
58 order += "memory"
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 format_up = "E: %ip (%speed)"
70 format_down = "E: down"
71 }
72 battery 0 {
74 format = "%status %percentage %remaining %emptytime"
75 format_down = "No battery"
76 status_chr = "⚡ CHR"
77 status_bat = "🔋 BAT"
78 status_unk = "? UNK"
79 status_full = "☻ FULL"
80 path = "/sys/class/power_supply/BAT%d/uevent"
81 low_threshold = 10
82 }
83 run_watch DHCP {
85 pidfile = "/var/run/dhclient*.pid"
86 }
87 run_watch VPNC {
89 # file containing the PID of a vpnc process
90 pidfile = "/var/run/vpnc/pid"
91 }
92 path_exists VPN {
94 # path exists when a VPN tunnel launched by nmcli/nm-applet is active
95 path = "/proc/sys/net/ipv4/conf/tun0"
96 }
97 tztime local {
99 format = "%Y-%m-%d %H:%M:%S"
100 hide_if_equals_localtime = true
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 memory {
118 format = "%used"
119 threshold_degraded = "10%"
120 format_degraded = "MEMORY: %free"
121 }
122 disk "/" {
124 format = "%free"
125 }
126 read_file uptime {
128 path = "/proc/uptime"
129 }
130 General
133 The colors directive will disable all colors if you set it to false.
134 You can also specify the colors that will be used to display "good",
135 "degraded" or "bad" values using the color_good, color_degraded or
136 color_bad directives, respectively. Those directives are only used if
137 color support is not disabled by the colors directive. The input format
138 for color values is the canonical RGB hexadecimal triplet (with no
139 separators between the colors), prefixed by a hash character ("#").
140 Example configuration:
142 color_good = "#00FF00"
144 Likewise, you can use the color_separator directive to specify the
146 color that will be used to paint the separator bar. The separator is
147 always output in color, even when colors are disabled by the colors
148 directive. This option has no effect when output_format is set to i3bar
149 or none.
150 The interval directive specifies the time in seconds for which i3status
152 will sleep before printing the next status line.
153 Using output_format you can choose which format strings i3status should
155 use in its output. Currently available are:
156 i3bar
158 i3bar comes with i3 and provides a workspace bar which does the
159 right thing in multi-monitor situations. It also comes with tray
160 support and can display the i3status output. This output type uses
161 JSON to pass as much meta-information to i3bar as possible (like
162 colors, which blocks can be shortened in which way, etc.).
163 dzen2
165 Dzen is a general purpose messaging, notification and menuing
166 program for X11. It was designed to be scriptable in any language
167 and integrate well with window managers like dwm, wmii and xmonad
168 though it will work with any window manager
169 xmobar
171 xmobar is a minimalistic, text based, status bar. It was designed
172 to work with the xmonad Window Manager.
173 lemonbar
175 lemonbar is a lightweight bar based entirely on XCB. It has full
176 UTF-8 support and is EWMH compliant.
177 term
179 Use ANSI Escape sequences to produce a terminal-output as close as
180 possible to the graphical outputs. This makes debugging your config
181 file a little bit easier because the terminal-output of i3status
182 becomes much more readable, but should only used for such quick
183 glances, because it will only support very basic output-features
184 (for example you only get 3 bits of color depth).
185 none
187 Does not use any color codes. Separates values by the pipe symbol
188 by default. This should be used with i3bar and can be used for
189 custom scripts.
190 It’s also possible to use the color_good, color_degraded, color_bad
192 directives to define specific colors per module. If one of these
193 directives is defined in a module section its value will override the
194 value defined in the general section just for this module.
195 If you don’t fancy the vertical separators between modules
197 i3status/i3bar uses by default, you can employ the separator directive
198 to configure how modules are separated. You can also disable the
199 default separator altogether by setting it to the empty string. You
200 might then define separation as part of a module’s format string. This
201 is your only option when using the i3bar output format as the separator
202 is drawn by i3bar directly otherwise. For the other output formats, the
203 provided non-empty string will be automatically enclosed with the
204 necessary coloring bits if color support is enabled.
205 i3bar supports Pango markup, allowing your format strings to specify
207 font, color, size, etc. by setting the markup directive to "pango".
208 Note that the ampersand ("&"), less-than ("<"), greater-than (">"),
209 single-quote ("'"), and double-quote (""") characters need to be
210 replaced with "&", "<", ">", "'", and """
211 respectively. This is done automatically for generated content (e.g.
212 wireless ESSID, time).
213 Example configuration:
215 general {
217 output_format = "xmobar"
218 separator = " "
219 }
220 order += "load"
222 order += "disk /"
223 load {
225 format = "[ load: %1min, %5min, %15min ]"
226 }
227 disk "/" {
228 format = "%avail"
229 }
230 IPv6
232 This module gets the IPv6 address used for outgoing connections (that
233 is, the best available public IPv6 address on your computer).
234 Example format_up: %ip
236 Example format_down: no IPv6
238 Disk
240 Gets used, free, available and total amount of bytes on the given
241 mounted filesystem.
242 These values can also be expressed in percentages with the
244 percentage_used, percentage_free, percentage_avail and
245 percentage_used_of_avail formats.
246 Byte sizes are presented in a human readable format using a set of
248 prefixes whose type can be specified via the "prefix_type" option.
249 Three sets of prefixes are available:
250 binary
252 IEC prefixes (Ki, Mi, Gi, Ti) represent multiples of powers of
253 1024. This is the default.
254 decimal
256 SI prefixes (k, M, G, T) represent multiples of powers of 1000.
257 custom
259 The custom prefixes (K, M, G, T) represent multiples of powers of
260 1024.
261 It is possible to define a low_threshold that causes the disk text to
263 be displayed using color_bad. The low_threshold type can be of
264 threshold_type "bytes_free", "bytes_avail", "percentage_free", or
265 "percentage_avail", where the former two can be prepended by a generic
266 prefix (k, m, g, t) having prefix_type. So, if you configure
267 low_threshold to 2, threshold_type to "gbytes_avail", and prefix_type
268 to "binary", and the remaining available disk space is below 2 GiB, it
269 will be colored bad. If not specified, threshold_type is assumed to be
270 "percentage_avail" and low_threshold to be set to 0, which implies no
271 coloring at all. You can customize the output format when below
272 low_threshold with format_below_threshold.
273 You can define a different format with the option "format_not_mounted"
275 which is used if the path does not exist or is not a mount point.
276 Defaults to "".
277 Example order: disk /mnt/usbstick
279 Example format: %free (%avail)/ %total
281 Example format: %percentage_used used, %percentage_free free,
283 %percentage_avail avail
284 Example prefix_type: custom
286 Example low_threshold: 5
288 Example format_below_threshold: Warning: %percentage_avail
290 Example threshold_type: percentage_free
292 Run-watch
294 Expands the given path to a pidfile and checks if the process ID found
295 inside is valid (that is, if the process is running). You can use this
296 to check if a specific application, such as a VPN client or your DHCP
297 client is running. There also is an option "format_down". You can hide
298 the output with format_down="".
299 Example order: run_watch DHCP
301 Example format: %title: %status
303 Path-exists
305 Checks if the given path exists in the filesystem. You can use this to
306 check if something is active, like for example a VPN tunnel managed by
307 NetworkManager. There also is an option "format_down". You can hide the
308 output with format_down="".
309 Example order: path_exists VPN
311 Example format: %title: %status
313 Wireless
315 Gets the link quality, frequency and ESSID of the given wireless
316 network interface. You can specify different format strings for the
317 network being connected or not connected. The quality is padded with
318 leading zeroes by default; to pad with something else use
319 format_quality.
320 The special interface name _first_ will be replaced by the first
322 wireless network interface found on the system (excluding devices
323 starting with "lo").
324 Example order: wireless wlan0
326 Example format_up: W: (%quality at %essid, %bitrate / %frequency) %ip
328 Example format_down: W: down
330 Example format_quality: "%03d%s"
332 Ethernet
334 Gets the IP address and (if possible) the link speed of the given
335 ethernet interface. If no IPv4 address is available and an IPv6 address
336 is, it will be displayed.
337 The special interface name _first_ will be replaced by the first
339 non-wireless network interface found on the system (excluding devices
340 starting with "lo").
341 Example order: ethernet eth0
343 Example format_up: E: %ip (%speed)
345 Example format_down: E: down
347 Battery
349 Gets the status (charging, discharging, unknown, full), percentage,
350 remaining time and power consumption (in Watts) of the given battery
351 and when it’s estimated to be empty. If you want to use the last full
352 capacity instead of the design capacity (when using the design
353 capacity, it may happen that your battery is at 23% when fully charged
354 because it’s old. In general, I want to see it this way, because it
355 tells me how worn off my battery is.), just specify last_full_capacity
356 = true. You can show seconds in the remaining time and empty time
357 estimations by setting hide_seconds = false.
358 If you want the battery percentage to be shown without decimals, add
360 integer_battery_capacity = true.
361 If your battery is represented in a non-standard path in /sys, be sure
363 to modify the "path" property accordingly, i.e. pointing to the uevent
364 file on your system. The first occurrence of %d gets replaced with the
365 battery number, but you can just hard-code a path as well.
366 It is possible to define a low_threshold that causes the battery text
368 to be colored red. The low_threshold type can be of threshold_type
369 "time" or "percentage". So, if you configure low_threshold to 10 and
370 threshold_type to "time", and your battery lasts another 9 minutes, it
371 will be colored red.
372 To show an aggregate of all batteries in the system, use "all" as the
374 number. In this case (for Linux), the /sys path must contain the "%d"
375 sequence. Otherwise, the number indicates the battery index as reported
376 in /sys.
377 Optionally custom strings including any UTF-8 symbols can be used for
379 different battery states. This makes it possible to display individual
380 symbols for each state (charging, discharging, unknown, full) Of course
381 it will also work with special iconic fonts, such as FontAwesome. If
382 any of these special status strings are omitted, the default (CHR, BAT,
383 UNK, FULL) is used.
384 Example order (for the first battery): battery 0
386 Example order (aggregate of all batteries): battery all
388 Example format: %status %remaining (%emptytime %consumption)
390 Example format_down: No battery
392 Example status_chr: ⚡ CHR
394 Example status_bat: 🔋 BAT
396 Example status_unk: ? UNK
398 Example status_full: ☻ FULL
400 Example low_threshold: 30
402 Example threshold_type: time
404 Example path (%d replaced by title number):
406 /sys/class/power_supply/CMB%d/uevent
407 Example path (ignoring the number): /sys/class/power_supply/CMB1/uevent
409 CPU-Temperature
411 Gets the temperature of the given thermal zone. It is possible to
412 define a max_threshold that will color the temperature red in case the
413 specified thermal zone is getting too hot. Defaults to 75 degrees C.
414 The output format when above max_threshold can be customized with
415 format_above_threshold.
416 Example order: cpu_temperature 0
418 Example format: T: %degrees °C
420 Example max_threshold: 42
422 Example format_above_threshold: Warning T above threshold: %degrees °C
424 Example path: /sys/devices/platform/coretemp.0/temp1_input
426 CPU Usage
428 Gets the percentual CPU usage from /proc/stat (Linux) or sysctl(3)
429 (FreeBSD/OpenBSD).
430 It is possible to define a max_threshold that will color the load value
432 red in case the CPU average over the last interval is getting higher
433 than the configured threshold. Defaults to 95. The output format when
434 above max_threshold can be customized with format_above_threshold.
435 It is possible to define a degraded_threshold that will color the load
437 value yellow in case the CPU average over the last interval is getting
438 higher than the configured threshold. Defaults to 90. The output format
439 when above degraded threshold can be customized with
440 format_above_degraded_threshold.
441 For displaying the Nth CPU usage, you can use the %cpu<N> format
443 string, starting from %cpu0. This feature is currently not supported in
444 FreeBSD.
445 Example order: cpu_usage
447 Example format: all: %usage CPU_0: %cpu0 CPU_1: %cpu1
449 Example max_threshold: 75
451 Example format_above_threshold: Warning above threshold: %usage
453 Example degraded_threshold: 25
455 Example format_above_degraded_threshold: Warning above degraded
457 threshold: %usage
458 Memory
460 Gets the memory usage from system on a Linux system from /proc/meminfo.
461 Other systems are currently not supported.
462 As format placeholders, total, used, free, available and shared are
464 available. These will print human readable values. It’s also possible
465 to prefix the placeholders with percentage_ to get a value in percent.
466 It’s possible to define a threshold_degraded and a threshold_critical
468 to color the status bar output in yellow or red, if the available
469 memory falls below the given threshold. Possible values of the
470 threshold can be any integer, suffixed with an iec symbol (T, G, M, K).
471 Alternatively, the integer can be suffixed by a percent sign, which
472 then rets evaluated relatively to total memory.
473 If the format_degraded parameter is given and either the critical or
475 the degraded threshold applies, format_degraded will get used as format
476 string. It acts equivalently to format.
477 As Linux' meminfo doesn’t expose the overall memory in use, there are
479 multiple methods to distinguish the actually used memory.
480 Example memory_used_method: memavailable ("total memory" -
482 "MemAvailable", matches free command)
483 Example memory_used_method: classical ("total memory" - "free" -
485 "buffers" - "cache", matches gnome system monitor)
486 Example order: memory
488 Example format: %free %available (%used) / %total
490 Example format: %percentage_used used, %percentage_free free,
492 %percentage_shared shared
493 Example threshold_degraded: 10%
495 Example threshold_critical: 5%
497 Example format_degraded: Memory LOW: %free
499 Load
501 Gets the system load (number of processes waiting for CPU time in the
502 last 1, 5 and 15 minutes). It is possible to define a max_threshold
503 that will color the load value red in case the load average of the last
504 minute is getting higher than the configured threshold. Defaults to 5.
505 The output format when above max_threshold can be customized with
506 format_above_threshold.
507 Example order: load
509 Example format: %1min %5min %15min
511 Example max_threshold: "0.1"
513 Example format_above_threshold: Warning: %1min %5min %15min
515 Time
517 Outputs the current time in the local timezone. To use a different
518 timezone, you can set the TZ environment variable, or use the tztime
519 module. See strftime(3) for details on the format string.
520 Example order: time
522 Example format: %Y-%m-%d %H:%M:%S
524 TzTime
526 Outputs the current time in the given timezone. If no timezone is
527 given, local time will be used. See strftime(3) for details on the
528 format string. The system’s timezone database is usually installed in
529 /usr/share/zoneinfo. Files below that path make for valid timezone
530 strings, e.g. for /usr/share/zoneinfo/Europe/Berlin you can set
531 timezone to Europe/Berlin in the tztime module. To override the locale
532 settings of your environment, set the locale option. To display time
533 only when the set timezone has different time from localtime, set
534 hide_if_equals_localtime to true.
535 Example order: tztime berlin
537 Example format: %Y-%m-%d %H:%M:%S %Z
539 Example timezone: Europe/Berlin
541 Example locale: de_DE.UTF-8
543 If you would like to use markup in this section, there is a separate
545 format_time option that is automatically escaped. Its output then
546 replaces %time in the format string.
547 Example configuration (markup):
549 tztime berlin {
551 format = "<span foreground='#ffffff'>time:</span> %time"
552 format_time = "%H:%M %Z"
553 timezone = "Europe/Berlin"
554 hide_if_equals_localtime = true
555 }
556 DDate
558 Outputs the current discordian date in user-specified format. See
559 ddate(1) for details on the format string. Note: Neither %. nor %X are
560 implemented yet.
561 Example order: ddate
563 Example format: %{%a, %b %d%}, %Y%N - %H
565 Volume
567 Outputs the volume of the specified mixer on the specified device.
568 PulseAudio and ALSA (Linux only) are supported. If PulseAudio is
569 absent, a simplified configuration can be used on FreeBSD and OpenBSD
570 due to the lack of ALSA, the device and mixer options can be ignored on
571 these systems. On these systems the OSS API is used instead to query
572 /dev/mixer directly if mixer_idx is -1, otherwise
573 /dev/mixer+mixer_idx+.
574 To get PulseAudio volume information, one must use the following format
576 in the device line:
577 device = "pulse"
579 or
581 device = "pulse:N"
583 where N is the index or name of the PulseAudio sink. You can obtain the
585 name of the sink with the following command:
586 $ pacmd list-sinks | grep name:
588 name: <alsa_output.pci-0000_00_14.2.analog-stereo>
589 The name is what’s inside the angle brackets, not including them. If no
591 sink is specified the default sink is used. If the device string is
592 missing or is set to "default", PulseAudio will be tried if detected
593 and will fallback to ALSA (Linux) or OSS (FreeBSD/OpenBSD).
594 Example order: volume master
596 Example format: ♪ (%devicename): %volume
598 Example format_muted: ♪ (%devicename): 0%%
600 Example configuration:
602 volume master {
604 format = "♪: %volume"
605 format_muted = "♪: muted (%volume)"
606 device = "default"
607 mixer = "Master"
608 mixer_idx = 0
609 }
610 Example configuration (PulseAudio):
612 volume master {
614 format = "♪: %volume"
615 format_muted = "♪: muted (%volume)"
616 device = "pulse:1"
617 }
618 volume master {
620 format = "♪: %volume"
621 format_muted = "♪: muted (%volume)"
622 device = "pulse:alsa_output.pci-0000_00_14.2.analog-stereo"
623 }
624 File Contents
626 Outputs the contents of the specified file. You can use this to check
627 contents of files on your system, for example /proc/uptime. By default
628 the function only reads the first 254 characters of the file, if you
629 want to override this set the Max_characters option. It will never read
630 beyond the first 4095 characters. If the file is not found "no file"
631 will be printed, if the file can’t be read "error read" will be
632 printed.
633 Example order: read_file UPTIME
635 Example format: "%title: %content"
637 Example format_bad: "%title - %errno: %error"
639 Example path: "/proc/uptime"
641 Example Max_characters: 255
643
645 When using the i3bar output format, there are a few additional options
646 that can be used with all modules to customize their appearance:
647 align
649 The alignment policy to use when the minimum width (see below) is
650 not reached. Either center (default), right or left.
651 min_width
653 The minimum width (in pixels) the module should occupy. If the
654 module takes less space than the specified size, the block will be
655 padded to the left and/or the right side, according to the defined
656 alignment policy. This is useful when you want to prevent the whole
657 status line from shifting when values take more or less space
658 between each iteration. The option can also be a string. In this
659 case, the width of the given text determines the minimum width of
660 the block. This is useful when you want to set a sensible minimum
661 width regardless of which font you are using, and at what
662 particular size. Please note that a number enclosed with quotes
663 will still be treated as a number.
664 separator
666 A boolean value which specifies whether a separator line should be
667 drawn after this block. The default is true, meaning the separator
668 line will be drawn. Note that if you disable the separator line,
669 there will still be a gap after the block, unless you also use
670 separator_block_width.
671 separator_block_width
673 The amount of pixels to leave blank after the block. In the middle
674 of this gap, a separator symbol will be drawn unless separator is
675 disabled. This is why the specified width should leave enough space
676 for the separator symbol.
677 Example configuration:
679 disk "/" {
681 format = "%avail"
682 align = "left"
683 min_width = 100
684 separator = false
685 separator_block_width = 1
686 }
687
689 After installing dzen2, you can directly use it with i3status. Just
690 ensure that output_format is set to dzen2. Note: min_width is not
691 supported.
692 Example for usage of i3status with dzen2:
694 i3status | dzen2 -fg white -ta r -w 1280 \
696 -fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"
697
699 To get xmobar to start, you might need to copy the default
700 configuration file to ~/.xmobarrc. Also, ensure that the output_format
701 option for i3status is set to xmobar. Note: min_width is not supported.
702 Example for usage of i3status with xmobar:
704 i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"
706
708 While talking about specific things, please understand this section as
709 a general explanation why your favorite information is not included in
710 i3status.
711 Let’s talk about CPU frequency specifically. Many people don’t
713 understand how frequency scaling works precisely. The generally
714 recommended CPU frequency governor ("ondemand") changes the CPU
715 frequency far more often than i3status could display it. The display
716 number is therefore often incorrect and doesn’t tell you anything
717 useful either.
718 In general, i3status wants to display things which you would look at
720 occasionally anyways, like the current date/time, whether you are
721 connected to a WiFi network or not, and if you have enough disk space
722 to fit that 4.3 GiB download.
723 However, if you need to look at some kind of information more than once
725 in a while, you are probably better off with a script doing that, which
726 pops up. After all, the point of computers is not to burden you with
727 additional boring tasks like repeatedly checking a number.
728
730 In i3status, we don’t want to implement process management again.
731 Therefore, there is no module to run arbitrary scripts or commands.
732 Instead, you should use your shell, for example like this:
733 Example for prepending the i3status output:
735 #!/bin/sh
737 # shell script to prepend i3status with more stuff
738 i3status | while :
740 do
741 read line
742 echo "mystuff | $line" || exit 1
743 done
744 Put that in some script, say .bin/my_i3status.sh and execute that
746 instead of i3status.
747 Note that if you want to use the JSON output format (with colors in
749 i3bar), you need to use a slightly more complex wrapper script. There
750 are examples in the contrib/ folder, see
751 https://github.com/i3/i3status/tree/master/contrib
752
754 When receiving SIGUSR1, i3status’s nanosleep() will be interrupted and
755 thus you will force an update. You can use killall -USR1 i3status to
756 force an update after changing the system volume, for example.
757
759 strftime(3), date(1), glob(3), dzen2(1), xmobar(1)
760
762 Michael Stapelberg and contributors
763 Thorsten Toepper
765 Baptiste Daroussin
767 Axel Wagner
769 Fernando Tarlá Cardoso Lemos
771i3status 2.13 01/26/2021 I3STATUS(1)