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_bitrate, format_noise, format_quality or format_signal.
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_bitrate: "%g %cb/s"
332 Example format_noise: "%03d%s"
334 Example format_quality: "%03d%s"
336 Example format_signal: "%03d%s"
338 Ethernet
340 Gets the IP address and (if possible) the link speed of the given
341 ethernet interface. If no IPv4 address is available and an IPv6 address
342 is, it will be displayed.
343 The special interface name _first_ will be replaced by the first
345 non-wireless network interface found on the system (excluding devices
346 starting with "lo").
347 Example order: ethernet eth0
349 Example format_up: E: %ip (%speed)
351 Example format_down: E: down
353 Battery
355 Gets the status (charging, discharging, unknown, full), percentage,
356 remaining time and power consumption (in Watts) of the given battery
357 and when it’s estimated to be empty. If you want to use the last full
358 capacity instead of the design capacity (when using the design
359 capacity, it may happen that your battery is at 23% when fully charged
360 because it’s old. In general, I want to see it this way, because it
361 tells me how worn off my battery is.), just specify last_full_capacity
362 = true. You can show seconds in the remaining time and empty time
363 estimations by setting hide_seconds = false.
364 If you want the battery percentage to be shown in another format, use
366 format_percentage. integer_battery_capacity = true is a legacy option
367 for format_percentage = "%.00f%s"
368 If your battery is represented in a non-standard path in /sys, be sure
370 to modify the path property accordingly, i.e. pointing to the uevent
371 file on your system. The first occurrence of %d gets replaced with the
372 battery number, but you can just hard-code a path as well.
373 It is possible to define a low_threshold that causes the battery text
375 to be colored color_bad. The low_threshold type can be of
376 threshold_type "time" or "percentage". So, if you configure
377 low_threshold to 10 and threshold_type to "time", and your battery
378 lasts another 9 minutes, it will be colored color_bad.
379 To show an aggregate of all batteries in the system, use "all" as the
381 number. In this case (for Linux), the /sys path must contain the "%d"
382 sequence. Otherwise, the number indicates the battery index as reported
383 in /sys.
384 Optionally custom strings including any UTF-8 symbols can be used for
386 different battery states. This makes it possible to display individual
387 symbols for each state (charging, discharging, unknown, full) Of course
388 it will also work with special iconic fonts, such as FontAwesome. If
389 any of these special status strings are omitted, the default (CHR, BAT,
390 UNK, FULL) is used.
391 Example order (for the first battery): battery 0
393 Example order (aggregate of all batteries): battery all
395 Example format: %status %remaining (%emptytime %consumption)
397 Example format_down: No battery
399 Example format_percentage: "%.02f%s"
401 Example status_chr: ⚡ CHR
403 Example status_bat: 🔋 BAT
405 Example status_unk: ? UNK
407 Example status_full: ☻ FULL
409 Example low_threshold: 30
411 Example threshold_type: time
413 Example path (%d replaced by title number):
415 /sys/class/power_supply/CMB%d/uevent
416 Example path (ignoring the number): /sys/class/power_supply/CMB1/uevent
418 CPU-Temperature
420 Gets the temperature of the given thermal zone. It is possible to
421 define a max_threshold that will color the temperature red in case the
422 specified thermal zone is getting too hot. Defaults to 75 degrees C.
423 The output format when above max_threshold can be customized with
424 format_above_threshold.
425 Example order: cpu_temperature 0
427 Example format: T: %degrees °C
429 Example max_threshold: 42
431 Example format_above_threshold: Warning T above threshold: %degrees °C
433 Example path: /sys/devices/platform/coretemp.0/temp1_input
435 CPU Usage
437 Gets the percentual CPU usage from /proc/stat (Linux) or sysctl(3)
438 (FreeBSD/OpenBSD).
439 It is possible to define a max_threshold that will color the load value
441 with color_bad in case the CPU average over the last interval is
442 getting higher than the configured threshold. Defaults to 95. The
443 output format when above max_threshold can be customized with
444 format_above_threshold.
445 It is possible to define a degraded_threshold that will color the load
447 value with color_degraded in case the CPU average over the last
448 interval is getting higher than the configured threshold. Defaults to
449 90. The output format when above degraded threshold can be customized
450 with format_above_degraded_threshold.
451 For displaying the Nth CPU usage, you can use the %cpu<N> format
453 string, starting from %cpu0. This feature is currently not supported in
454 FreeBSD.
455 Example order: cpu_usage
457 Example format: all: %usage CPU_0: %cpu0 CPU_1: %cpu1
459 Example max_threshold: 75
461 Example format_above_threshold: Warning above threshold: %usage
463 Example degraded_threshold: 25
465 Example format_above_degraded_threshold: Warning above degraded
467 threshold: %usage
468 Memory
470 Gets the memory usage from system on a Linux system from /proc/meminfo.
471 Other systems are currently not supported.
472 As format placeholders, total, used, free, available and shared are
474 available. These will print human readable values. It’s also possible
475 to prefix the placeholders with percentage_ to get a value in percent.
476 It’s possible to define a threshold_degraded and a threshold_critical
478 to color the status bar output in color_degraded or color_bad, if the
479 available memory falls below the given threshold. Possible values of
480 the threshold can be any integer, suffixed with an iec symbol (T, G, M,
481 K). Alternatively, the integer can be suffixed by a percent sign, which
482 then gets evaluated relatively to total memory.
483 If the format_degraded parameter is given and either the critical or
485 the degraded threshold applies, format_degraded will get used as format
486 string. It acts equivalently to format.
487 It’s also possible to define the unit for the various format
489 placeholders. As /proc/meminfo returns the memory in kB they will be
490 converted to the given unit. If no unit is given or the auto option is
491 used, the conversion will select the maximum possible unit.
492 As the converted format placeholder will be a decimal number, the
494 number of decimals can be configured via the decimals option. If no
495 such option is given the converted format placeholder will have one
496 decimal.
497 As Linux' meminfo doesn’t expose the overall memory in use, there are
499 multiple methods to distinguish the actually used memory.
500 Example memory_used_method: memavailable ("total memory" -
502 "MemAvailable", matches free command)
503 Example memory_used_method: classical ("total memory" - "free" -
505 "buffers" - "cache", matches gnome system monitor)
506 Example order: memory
508 Example format: %free %available (%used) / %total
510 Example format: %percentage_used used, %percentage_free free,
512 %percentage_shared shared
513 Example unit: auto, Ki, Mi, Gi, Ti
515 Example decimals: 0, 1, 2, 3
517 Example threshold_degraded: 10%
519 Example threshold_critical: 5%
521 Example format_degraded: Memory LOW: %free
523 Load
525 Gets the system load (number of processes waiting for CPU time in the
526 last 1, 5 and 15 minutes). It is possible to define a max_threshold
527 that will color the load value color_bad in case the load average of
528 the last minute is getting higher than the configured threshold.
529 Defaults to 5. The output format when above max_threshold can be
530 customized with format_above_threshold.
531 Example order: load
533 Example format: %1min %5min %15min
535 Example max_threshold: "0.1"
537 Example format_above_threshold: Warning: %1min %5min %15min
539 Time
541 Outputs the current time in the local timezone. To use a different
542 timezone, you can set the TZ environment variable, or use the tztime
543 module. See strftime(3) for details on the format string.
544 Example order: time
546 Example format: %Y-%m-%d %H:%M:%S
548 TzTime
550 Outputs the current time in the given timezone. If no timezone is
551 given, local time will be used. See strftime(3) for details on the
552 format string. The system’s timezone database is usually installed in
553 /usr/share/zoneinfo. Files below that path make for valid timezone
554 strings, e.g. for /usr/share/zoneinfo/Europe/Berlin you can set
555 timezone to Europe/Berlin in the tztime module. To override the locale
556 settings of your environment, set the locale option. To display time
557 only when the set timezone has different time from localtime, set
558 hide_if_equals_localtime to true.
559 Example order: tztime berlin
561 Example format: %Y-%m-%d %H:%M:%S %Z
563 Example timezone: Europe/Berlin
565 Example locale: de_DE.UTF-8
567 If you would like to use markup in this section, there is a separate
569 format_time option that is automatically escaped. Its output then
570 replaces %time in the format string.
571 Example configuration (markup):
573 tztime berlin {
575 format = "<span foreground='#ffffff'>time:</span> %time"
576 format_time = "%H:%M %Z"
577 timezone = "Europe/Berlin"
578 hide_if_equals_localtime = true
579 }
580 DDate
582 Outputs the current discordian date in user-specified format. See
583 ddate(1) for details on the format string. Note: Neither %. nor %X are
584 implemented yet.
585 Example order: ddate
587 Example format: %{%a, %b %d%}, %Y%N - %H
589 Volume
591 Outputs the volume of the specified mixer on the specified device.
592 PulseAudio and ALSA (Linux only) are supported. If PulseAudio is
593 absent, a simplified configuration can be used on FreeBSD and OpenBSD
594 due to the lack of ALSA, the device and mixer options can be ignored on
595 these systems. On these systems the OSS API is used instead to query
596 /dev/mixer directly if mixer_idx is -1, otherwise
597 /dev/mixer+mixer_idx+.
598 To get PulseAudio volume information, one must use the following format
600 in the device line:
601 device = "pulse"
603 or
605 device = "pulse:N"
607 where N is the index or name of the PulseAudio sink. You can obtain the
609 name of the sink with the following command:
610 $ pacmd list-sinks | grep name:
612 name: <alsa_output.pci-0000_00_14.2.analog-stereo>
613 The name is what’s inside the angle brackets, not including them. If no
615 sink is specified the default sink is used. If the device string is
616 missing or is set to "default", PulseAudio will be tried if detected
617 and will fallback to ALSA (Linux) or OSS (FreeBSD/OpenBSD).
618 Example order: volume master
620 Example format: ♪ (%devicename): %volume
622 Example format_muted: ♪ (%devicename): 0%%
624 Example configuration:
626 volume master {
628 format = "♪: %volume"
629 format_muted = "♪: muted (%volume)"
630 device = "default"
631 mixer = "Master"
632 mixer_idx = 0
633 }
634 Example configuration (PulseAudio):
636 volume master {
638 format = "♪: %volume"
639 format_muted = "♪: muted (%volume)"
640 device = "pulse:1"
641 }
642 volume master {
644 format = "♪: %volume"
645 format_muted = "♪: muted (%volume)"
646 device = "pulse:alsa_output.pci-0000_00_14.2.analog-stereo"
647 }
648 File Contents
650 Outputs the contents of the specified file. You can use this to check
651 contents of files on your system, for example /proc/uptime. By default
652 the function only reads the first 254 characters of the file, if you
653 want to override this set the Max_characters option. It will never read
654 beyond the first 4095 characters. If the file is not found "no file"
655 will be printed, if the file can’t be read "error read" will be
656 printed.
657 Example order: read_file UPTIME
659 Example format: "%title: %content"
661 Example format_bad: "%title - %errno: %error"
663 Example path: "/proc/uptime"
665 Example Max_characters: 255
667
669 When using the i3bar output format, there are a few additional options
670 that can be used with all modules to customize their appearance:
671 align
673 The alignment policy to use when the minimum width (see below) is
674 not reached. Either center (default), right or left.
675 min_width
677 The minimum width (in pixels) the module should occupy. If the
678 module takes less space than the specified size, the block will be
679 padded to the left and/or the right side, according to the defined
680 alignment policy. This is useful when you want to prevent the whole
681 status line from shifting when values take more or less space
682 between each iteration. The option can also be a string. In this
683 case, the width of the given text determines the minimum width of
684 the block. This is useful when you want to set a sensible minimum
685 width regardless of which font you are using, and at what
686 particular size. Please note that a number enclosed with quotes
687 will still be treated as a number.
688 separator
690 A boolean value which specifies whether a separator line should be
691 drawn after this block. The default is true, meaning the separator
692 line will be drawn. Note that if you disable the separator line,
693 there will still be a gap after the block, unless you also use
694 separator_block_width.
695 separator_block_width
697 The amount of pixels to leave blank after the block. In the middle
698 of this gap, a separator symbol will be drawn unless separator is
699 disabled. This is why the specified width should leave enough space
700 for the separator symbol.
701 Example configuration:
703 disk "/" {
705 format = "%avail"
706 align = "left"
707 min_width = 100
708 separator = false
709 separator_block_width = 1
710 }
711
713 After installing dzen2, you can directly use it with i3status. Just
714 ensure that output_format is set to dzen2. Note: min_width is not
715 supported.
716 Example for usage of i3status with dzen2:
718 i3status | dzen2 -fg white -ta r -w 1280 \
720 -fn "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso8859-1"
721
723 To get xmobar to start, you might need to copy the default
724 configuration file to ~/.xmobarrc. Also, ensure that the output_format
725 option for i3status is set to xmobar. Note: min_width is not supported.
726 Example for usage of i3status with xmobar:
728 i3status | xmobar -o -t "%StdinReader%" -c "[Run StdinReader]"
730
732 While talking about specific things, please understand this section as
733 a general explanation why your favorite information is not included in
734 i3status.
735 Let’s talk about CPU frequency specifically. Many people don’t
737 understand how frequency scaling works precisely. The generally
738 recommended CPU frequency governor ("ondemand") changes the CPU
739 frequency far more often than i3status could display it. The display
740 number is therefore often incorrect and doesn’t tell you anything
741 useful either.
742 In general, i3status wants to display things which you would look at
744 occasionally anyways, like the current date/time, whether you are
745 connected to a WiFi network or not, and if you have enough disk space
746 to fit that 4.3 GiB download.
747 However, if you need to look at some kind of information more than once
749 in a while, you are probably better off with a script doing that, which
750 pops up. After all, the point of computers is not to burden you with
751 additional boring tasks like repeatedly checking a number.
752
754 In i3status, we don’t want to implement process management again.
755 Therefore, there is no module to run arbitrary scripts or commands.
756 Instead, you should use your shell, for example like this:
757 Example for prepending the i3status output:
759 #!/bin/sh
761 # shell script to prepend i3status with more stuff
762 i3status | while :
764 do
765 read line
766 echo "mystuff | $line" || exit 1
767 done
768 Put that in some script, say .bin/my_i3status.sh and execute that
770 instead of i3status.
771 Note that if you want to use the JSON output format (with colors in
773 i3bar), you need to use a slightly more complex wrapper script. There
774 are examples in the contrib/ folder, see
775 https://github.com/i3/i3status/tree/master/contrib
776
778 When receiving SIGUSR1, i3status’s nanosleep() will be interrupted and
779 thus you will force an update. You can use killall -USR1 i3status to
780 force an update after changing the system volume, for example.
781
783 strftime(3), date(1), glob(3), dzen2(1), xmobar(1)
784
786 Michael Stapelberg and contributors
787 Thorsten Toepper
789 Baptiste Daroussin
791 Axel Wagner
793 Fernando Tarlá Cardoso Lemos
795i3status 2.14 11/09/2021 I3STATUS(1)