amd_gpu

Display the stats of your AMD GPU

Configuration

Example

[[block]]
block = "amd_gpu"
format = " $icon $utilization "
format_alt = " $icon MEM: $vram_used_percents ($vram_used/$vram_total) "
interval = 1

Icons Used

•

gpu

apt

Pending updates available for your Debian/Ubuntu based system

Behind the scenes this uses apt, and in order to run it without root privileges i3status-rust will create its own package database in /tmp/i3rs-apt/ which may take up several MB or more. If you have a custom apt config then this block may not work as expected - in that case please open an issue.

Tip: You can grab the list of available updates using APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable

Configuration

Example

Update the list of pending updates every thirty minutes (1800 seconds):

[[block]]
block = "apt"
interval = 1800
format = " $icon $count updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
critical_updates_regex = "(linux|linux-lts|linux-zen)"
[[block.click]]
### shows dmenu with cached available updates. Any dmenu alternative should also work.
button = "left"
cmd = "APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable | tail -n +2 | rofi -dmenu"
[[block.click]]
### Updates the block on right click
button = "right"
update = true

Icons Used

•

update

backlight

The brightness of a backlight device

This block reads brightness information directly from the filesystem, so it works under both X11 and Wayland. The block uses inotify to listen for changes in the device’s brightness directly, so there is no need to set an update interval. This block uses DBus to set brightness level using the mouse wheel, but will fallback to sysfs if systemd-logind is not used.

Root scaling

Some devices expose raw values that are best handled with nonlinear scaling. The human perception of lightness is close to the cube root of relative luminance, so settings for root_scaling between 2.4 and 3.0 are worth trying. For devices with few discrete steps this should be 1.0 (linear). More information: https://en.wikipedia.org/wiki/Lightness

Configuration

Example

[[block]]
block = "backlight"
device = "intel_backlight"

Hide missing backlight:

[[block]]
block = "backlight"
missing_format = ""

calibright

Additional display brightness calibration can be set in $XDG_CONFIG_HOME/calibright/config.toml See https://github.com/bim9262/calibright for more details. This block will override any global config set in $XDG_CONFIG_HOME/calibright/config.toml

D-Bus Fallback

If you don’t use systemd-logind i3status-rust will attempt to set the brightness using sysfs. In order to do this you’ll need to have write permission. You can do this by writing a udev rule for your system.

First, check that your user is a member of the “video” group using the groups command. Then add a rule in the /etc/udev/rules.d/ directory containing the following, for example in backlight.rules:

ACTION=="add", SUBSYSTEM=="backlight", GROUP="video", MODE="0664"

This will allow the video group to modify all backlight devices. You will also need to restart for this rule to take effect.

Icons Used

•

backlight (as a progression)

battery

Information about the internal power supply

This block can display the current battery state (Full, Charging or Discharging), percentage charged and estimate time until (dis)charged for an internal power supply.

Configuration

time has been deprecated in favor of time_remaining.

Examples

Basic usage:

[[block]]
block = "battery"
format = " $icon $percentage "

[[block]]
block = "battery"
format = " $percentage {$time_remaining.dur(hms:true, min_unit:m) |}"
device = "DisplayDevice"
driver = "upower"

Hide missing battery:

[[block]]
block = "battery"
missing_format = ""

Icons Used

•

bat (as a progression)

•

bat_charging (as a progression)

•

bat_not_available

bluetooth

Monitor Bluetooth device

This block displays the connectivity of a given Bluetooth device and the battery level if this is supported. Relies on the Bluez D-Bus API.

When the device can be identified as an audio headset, a keyboard, joystick, or mouse, use the relevant icon. Otherwise, fall back on the generic Bluetooth symbol.

Right-clicking the block will attempt to connect (or disconnect) the device.

Note: battery level information is not reported for some devices. https://wiki.archlinux.org/title/bluetooth#Enabling_experimental_features Enabling experimental features of bluez may fix it.

Configuration

Examples

This example just shows the icon when device is connected.

[[block]]
block = "bluetooth"
mac = "00:18:09:92:1B:BA"
disconnected_format = ""
format = " $icon "
[block.battery_state]
"0..20" = "critical"
"21..70" = "warning"
"71..100" = "good"

Icons Used

•

headphones for bluetooth devices identifying as “audio-card”, “audio-headset” or “audio-headphones”

•

joystick for bluetooth devices identifying as “input-gaming”

•

keyboard for bluetooth devices identifying as “input-keyboard”

•

mouse for bluetooth devices identifying as “input-mouse”

•

bluetooth for all other devices

calendar

Calendar

This block displays upcoming calendar events retrieved from a CalDav ICalendar server.

Configuration

Source Configuration

Note: Currently only one source is supported

Examples

Unauthenticated

[[block]]
block = "calendar"
next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary "
ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) "
no_events_format = " $icon no events "
fetch_interval = 30
alternate_events_interval = 10
events_within_hours = 48
warning_threshold = 600
browser_cmd = "firefox"
[[block.source]]
url = "https://caldav.example.com/calendar/"
calendars = ["user/calendar"]
[block.source.auth]
type = "unauthenticated"

Basic Authentication

[[block]]
block = "calendar"
next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary "
ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) "
no_events_format = " $icon no events "
fetch_interval = 30
alternate_events_interval = 10
events_within_hours = 48
warning_threshold = 600
browser_cmd = "firefox"
[[block.source]]
url = "https://caldav.example.com/calendar/"
calendars = [ "Holidays" ]
[block.source.auth]
type = "basic"
username = "your_username"
password = "your_password"

Note: You can also configure the username and password in a separate TOML file.

~/.config/i3status-rust/example_credentials.toml

username = "my-username"
password = "my-password"

Source auth configuration with credentials_path:

[block.source.auth]
type = "basic"
credentials_path = "~/.config/i3status-rust/example_credentials.toml"

OAuth2 Authentication (Google Calendar)

To access the CalDav API of Google, follow these steps to enable the API and obtain the client_id and client_secret: 1. Go to the Google Cloud Console: Navigate to the Google Cloud Console. 2. Create a New Project: If you don’t already have a project, click on the project dropdown and select “New Project”. Give your project a name and click “Create”. 3. Enable the CalDAV API: In the project dashboard, go to the “APIs & Services” > “Library”. Search for “CalDAV API” and click on it, then click “Enable”. 4. Set Up OAuth Consent Screen: Go to “APIs & Services” > “OAuth consent screen”. Fill out the required information and save. 5. Create Credentials: - Navigate to “APIs & Services” > “Credentials”. - Click “Create Credentials” and select “OAuth 2.0 Client IDs”. - Configure the consent screen if you haven’t already. - Set the application type to “Web application”. - Add your authorized redirect URIs. For example, http://localhost:8080. - Click “Create” and note down the client_id and client_secret. 6. Download the Credentials: Click on the download icon next to your OAuth 2.0 Client ID to download the JSON file containing your client ID and client secret. Use these values in your configuration.

[[block]]
block = "calendar"
next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary "
ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) "
no_events_format = " $icon no events "
fetch_interval = 30
alternate_events_interval = 10
events_within_hours = 48
warning_threshold = 600
browser_cmd = "firefox"
[[block.source]]
url = "https://apidata.googleusercontent.com/caldav/v2/"
calendars = ["primary"]
[block.source.auth]
type = "oauth2"
client_id = "your_client_id"
client_secret = "your_client_secret"
auth_url = "https://accounts.google.com/o/oauth2/auth"
token_url = "https://oauth2.googleapis.com/token"
auth_token = "~/.config/i3status-rust/calendar.auth_token"
redirect_port = 8080
scopes = ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"]

Note: You can also configure the client_id and client_secret in a separate TOML file.

~/.config/i3status-rust/google_credentials.toml

client_id = "my-client_id"
client_secret = "my-client_secret"

Source auth configuration with credentials_path:

[block.source.auth]
type = "oauth2"
credentials_path = "~/.config/i3status-rust/google_credentials.toml"
auth_url = "https://accounts.google.com/o/oauth2/auth"
token_url = "https://oauth2.googleapis.com/token"
auth_token = "~/.config/i3status-rust/calendar.auth_token"
redirect_port = 8080
scopes = ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"]

Format Configuration

The format configuration is a string that can include placeholders to be replaced with dynamic content. Placeholders can be: - $summary: Summary of the event - $description: Description of the event - $url: Url of the event - $location: Location of the event - $start: Start time of the event - $end: End time of the event

Icons Used

•

calendar

cpu

CPU statistics

Configuration

Example

[[block]]
block = "cpu"
interval = 1
format = " $icon $barchart $utilization "
format_alt = " $icon $frequency{ $boost|} "
info_cpu = 20
warning_cpu = 50
critical_cpu = 90

Icons Used

•

cpu (as a progression)

•

cpu_boost_on

•

cpu_boost_off

custom

The output of a custom shell command

For further customisation, use the json option and have the shell command output valid JSON in the schema below:

{"icon": "...", "state": "...", "text": "...", "short_text": "..."}

icon is optional (default ““) state is optional, it may be Idle, Info, Good, Warning, Critical (default Idle) short_text is optional.

Configuration

Examples

Display temperature, update every 10 seconds:

[[block]]
block = "custom"
command = ''' cat /sys/class/thermal/thermal_zone0/temp | awk '{printf("%.1f\n",$1/1000)}' '''

Cycle between “ON” and “OFF”, update every 1 second, run next cycle command when block is clicked:

[[block]]
block = "custom"
cycle = ["echo ON", "echo OFF"]
interval = 1
[[block.click]]
button = "left"
action = "cycle"

Use JSON output:

[[block]]
block = "custom"
command = "echo '{\"icon\":\"weather_thunder\",\"state\":\"Critical\", \"text\": \"Danger!\"}'"
json = true

Display kernel, update the block only once:

[[block]]
block = "custom"
command = "uname -r"
interval = "once"

Display the screen brightness on an intel machine and update this only when pkill -SIGRTMIN+4 i3status-rs is called:

[[block]]
block = "custom"
command = ''' cat /sys/class/backlight/intel_backlight/brightness | awk '{print $1}' '''
signal = 4
interval = "once"

Update block when one or more specified files are modified:

[[block]]
block = "custom"
command = "cat custom_status"
watch_files = ["custom_status"]
interval = "once"

TODO:

•

Use shellexpand

custom_dbus

A block controlled by the DBus

This block creates a new DBus object in rs.i3status service. This object implements rs.i3status.custom interface which allows you to set block’s icon, text and state.

Output of busctl --user introspect rs.i3status /<path> rs.i3status.custom:

NAME                                TYPE      SIGNATURE RESULT/VALUE FLAGS
rs.i3status.custom                  interface -         -            -
.SetIcon                            method    s         s            -
.SetState                           method    s         s            -
.SetText                            method    ss        s            -

Configuration

Example

Config:

[[block]]
block = "custom_dbus"
path = "/my_path"

Usage:

### set full text to 'hello' and short text to 'hi'
busctl --user call rs.i3status /my_path rs.i3status.custom SetText ss hello hi
### set icon to 'music'
busctl --user call rs.i3status /my_path rs.i3status.custom SetIcon s music
### set state to 'good'
busctl --user call rs.i3status /my_path rs.i3status.custom SetState s good

Because it’s impossible to publish objects to the same name from different processes, having multiple dbus blocks in different bars won’t work. As a workaround, you can set the env var I3RS_DBUS_NAME to set the interface a bar works on to differentiate between different processes. For example, setting this to `top', will allow you to use rs.i3status.top.

TODO

•

Send a signal on click?

disk_space

Disk usage statistics

Configuration

Examples

[[block]]
block = "disk_space"
info_type = "available"
alert_unit = "GB"
alert = 10.0
warning = 15.0
format = " $icon $available "
format_alt = " $icon $available / $total "

Update block on right click:

[[block]]
block = "disk_space"
[[block.click]]
button = "right"
update = true

Show the block only if less than 10GB is available:

[[block]]
block = "disk_space"
format = " $free.eng(range:..10e9) |"

Icons Used

•

disk_drive

dnf

Pending updates available for your Fedora system

Configuration

Example

Update the list of pending updates every thirty minutes (1800 seconds):

[[block]]
block = "dnf"
interval = 1800
format = " $icon $count.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
critical_updates_regex = "(linux|linux-lts|linux-zen)"
[[block.click]]
### shows dmenu with cached available updates. Any dmenu alternative should also work.
button = "left"
cmd = "dnf list -q --upgrades | tail -n +2 | rofi -dmenu"

Icons Used

•

update

docker

Local docker daemon status

Configuration

Example

[[block]]
block = "docker"
interval = 2
format = " $icon $running/$total "

Icons Used

•

docker

external_ip

External IP address and various information about it

Configuration

Example

[[block]]
block = "external_ip"
format = " $ip $country_code "

Notes

All the information comes from https://ipapi.co/json/ Check their documentation here: https://ipapi.co/api/#complete-location5

The IP is queried, 1) When i3status-rs starts, 2) When a signal is received on D-Bus about a network configuration change, 3) Every 5 minutes. This periodic refresh exists to catch IP updates that don’t trigger a notification, for example due to a IP refresh at the router.

Flags: They are not icons but unicode glyphs. You will need a font that includes them. Tested with: https://www.babelstone.co.uk/Fonts/Flags.html

focused_window

Currently focused window

This block displays the title and/or the active marks (when used with sway/i3) of the currently focused window. Supported WMs are: sway, i3 and most wlroots-based compositors. See driver option for more info.

Configuration

Example

[[block]]
block = "focused_window"
[block.format]
full = " $title.str(max_w:15) |"
short = " $title.str(max_w:10) |"

This example instead of hiding block when the window’s title is empty displays “Missing”

[[block]]
block = "focused_window"
format = " $title.str(0,21) | Missing "

github

The number of GitHub notifications

This block shows the unread notification count for a GitHub account. A GitHub personal access token with the “notifications” scope is required, and must be passed using the I3RS_GITHUB_TOKEN environment variable or token configuration option. Optionally the colour of the block is determined by the highest notification in the following lists from highest to lowest: critical,warning,info,good

Configuration

All the placeholders are numbers without a unit.

Examples

[[block]]
block = "github"
format = " $icon $total.eng(w:1)|$mention.eng(w:1) "
interval = 60
token = "..."

[[block]]
block = "github"
token = "..."
format = " $icon $total.eng(w:1) "
info = ["total"]
warning = ["mention","review_requested"]
hide_if_total_is_zero = true

Icons Used

•

github

hueshift

Manage display temperature

This block displays the current color temperature in Kelvin. When scrolling upon the block the color temperature is changed. A left click on the block sets the color temperature to click_temp that is by default to 6500K. A right click completely resets the color temperature to its default value (6500K).

Configuration

Available Hue Shifters

Note that at the moment, only wl_gammarelay and wl_gammarelay_rs subscribe to the events and update the bar when the temperature is modified externally. Also, these are the only drivers at the moment that work under Wayland without flickering.

Example

[[block]]
block = "hueshift"
hue_shifter = "redshift"
step = 50
click_temp = 3500

A hard limit is set for the max_temp to 10000K and the same for the min_temp which is 1000K. The step has a hard limit as well, defined to 500K to avoid too brutal changes.

kdeconnect

KDEConnect indicator

Display info from the currently connected device in KDEConnect, updated asynchronously.

Block colours are updated based on the battery level, unless all bat_* thresholds are set to 0, in which case the block colours will depend on the notification count instead.

Configuration

Example

Do not show the name, do not set the “good” state.

[[block]]
block = "kdeconnect"
format = " $icon {$bat_icon $bat_charge |}{$notif_icon |}{$network_icon$network_strength $network_type |}"
bat_good = 101

Icons Used

•

bat (as a progression)

•

bat_charging (as a progression)

•

net_cellular (as a progression)

•

notification

•

phone

•

phone_disconnected

keyboard_layout

Keyboard layout indicator

Four drivers are available: - setxkbmap which polls setxkbmap to get the current layout - xkbswitch which utilizes XkbSwitch to monitor and retrieve the current layout and variant - localebus which can read asynchronous updates from the systemd org.freedesktop.locale1 D-Bus path - kbddbus which uses kbdd to monitor per-window layout changes via DBus - sway which can read asynchronous updates from the sway IPC

Which of these methods is appropriate will depend on your system setup.

Configuration

Examples

Check setxkbmap every 15 seconds:

[[block]]
block = "keyboard_layout"
driver = "setxkbmap"
interval = 15

Check xkbswitch every 15 seconds

[[block]]
block = "keyboard_layout"
driver = "xkbswitch"
interval = 15

Listen to D-Bus for changes:

[[block]]
block = "keyboard_layout"
driver = "localebus"

Listen to kbdd for changes, the text is in the following format: “English (US)” - {$layout ($variant)} use block.mappings to override with shorter names as shown below. Also use format = ” $layout ($variant) ” to see the full text to map, or you can use: dbus-monitor interface=ru.gentoo.kbdd to see the exact variant spelling

[[block]]
block = "keyboard_layout"
driver = "kbddbus"
[block.mappings]
"English (US)" = "us"
"Bulgarian (new phonetic)" = "bg"

Listen to sway for changes:

[[block]]
block = "keyboard_layout"
driver = "sway"
sway_kb_identifier = "1133:49706:Gaming_Keyboard_G110"

Listen to sway for changes and override mappings:

[[block]]
block = "keyboard_layout"
driver = "sway"
format = " $layout "
[block.mappings]
"English (Workman)" = "EN"
"Russian (N/A)" = "RU"

load

System load average

Configuration

Example

[[block]]
block = "load"
format = " $icon 1min avg: $1m.eng(w:4) "
interval = 1

Icons Used

•

cogs

maildir

Unread mail. Only supports maildir format.

Note that you need to enable maildir feature to use this block:

cargo build --release --features maildir

Configuration

Examples

[[block]]
block = "maildir"
interval = 60
inboxes = ["~/mail/local", "~/maildir/account1/*"]
threshold_warning = 1
threshold_critical = 10
display_type = "new"

Icons Used

•

mail

memory

Memory and swap usage

Configuration

Examples

[[block]]
block = "memory"
format = " $icon $mem_used_percents.eng(w:1) "
format_alt = " $icon_swap $swap_free.eng(w:3,u:B,p:Mi)/$swap_total.eng(w:3,u:B,p:Mi)($swap_used_percents.eng(w:2)) "
interval = 30
warning_mem = 70
critical_mem = 90

Show swap and hide if it is zero:

[[block]]
block = "memory"
format = " $icon $swap_used.eng(range:1..) |"

Icons Used

•

memory_mem

•

memory_swap

menu

A custom menu

This block allows you to quickly run a custom shell command. Left-click on this block to activate it, then scroll through configured items. Left-click on the item to run it and optionally confirm your action by left-clicking again. Right-click any time to deactivate this block.

Configuration

Example

[[block]]
block = "menu"
text = "\uf011"
[[block.items]]
display = " ->   Sleep   <-"
cmd = "systemctl suspend"
[[block.items]]
display = " -> Power Off <-"
cmd = "poweroff"
confirm_msg = "Are you sure you want to power off?"
[[block.items]]
display = " ->  Reboot   <-"
cmd = "reboot"
confirm_msg = "Are you sure you want to reboot?"

music

The current song title and artist

Also provides buttons for play/pause, previous and next.

Supports all music players that implement the https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html MediaPlayer2 Interface. This includes:

•

Spotify

•

VLC

•

mpd (via mpDris2)

and many others.

By default the block tracks all players available on the MPRIS bus. Right clicking on the block will cycle it to the next player. You can pin the widget to a given player via the “player” setting.

Configuration

Note: All placeholders except icon can be absent. See the examples below to learn how to handle this.

Examples

Show the currently playing song on Spotify only, with play & next buttons and limit the width to 20 characters:

[[block]]
block = "music"
format = " $icon {$combo.str(max_w:20) $play $next |}"
player = "spotify"

Same thing for any compatible player, takes the first active on the bus, but ignores “mpd” or anything with “kdeconnect” in the name:

[[block]]
block = "music"
format = " $icon {$combo.str(max_w:20) $play $next |}"
interface_name_exclude = [".*kdeconnect.*", "mpd"]

Same as above, but displays with rotating text

[[block]]
block = "music"
format = " $icon {$combo.str(max_w:20,rot_interval:0.5) $play $next |}"
interface_name_exclude = [".*kdeconnect.*", "mpd"]

Click anywhere to play/pause, middle click to toggle format:

[[block]]
block = "music"
format = " format 1 "
format_alt = " format 2 "
[[block.click]]
button = "left"
action = "play_pause"
[[block.click]]
button = "middle"
widget = "."
action = "toggle_format"

Scroll to change the player volume, use the forward and back buttons to seek:

[[block]]
block = "music"
format = " $icon $volume_icon $combo $play $next| "
seek_step_secs = 10
[[block.click]]
button = "up"
action = "volume_up"
[[block.click]]
button = "down"
action = "volume_down"
[[block.click]]
button = "forward"
action = "seek_forward"
[[block.click]]
button = "back"
action = "seek_backward"

Icons Used

•

music

•

music_next

•

music_play

•

music_prev

•

volume_muted

•

volume (as a progression)

net

Network information

This block uses sysfs and netlink and thus does not require any external dependencies.

Configuration

Example

Display WiFi info if available

[[block]]
block = "net"
format = " $icon {$signal_strength $ssid $frequency|Wired connection} via $device "

Display exact device

[[block]]
block = "net"
device = "^wlo0$"

Icons Used

•

net_loopback

•

net_vpn

•

net_wired

•

net_wireless (as a progression)

•

net_up

•

net_down

notify

Display and toggle the state of notifications daemon

Left-clicking on this block will enable/disable notifications.

Configuration

Examples

How to use paused flag

[[block]]
block = "notify"
format = " $icon {$paused{Off}|On} "

How to use notification_count

[[block]]
block = "notify"
format = " $icon {($notification_count.eng(w:1)) |}"

How to remap actions

[[block]]
block = "notify"
driver = "swaync"
[[block.click]]
button = "left"
action = "show"
[[block.click]]
button = "right"
action = "toggle_paused"

Icons Used

•

bell

•

bell-slash

notmuch

Count of notmuch messages

This block queries a notmuch database and displays the count of messages.

The simplest configuration will return the total count of messages in the notmuch database stored at $HOME/.mail

Note that you need to enable notmuch feature to use this block:

cargo build --release --features notmuch

Configuration

Example

[[block]]
block = "notmuch"
query = "tag:alert and not tag:trash"
threshold_warning = 1
threshold_critical = 10
[[block.click]]
button = "left"
update = true

Icons Used

•

mail

nvidia_gpu

Display the stats of your NVidia GPU

By default show_temperature shows the used memory. Clicking the left mouse on the “temperature” part of the block will alternate it between showing used or total available memory.

Clicking the left mouse button on the “fan speed” part of the block will cause it to enter into a fan speed setting mode. In this mode you can scroll the mouse wheel over the block to change the fan speeds, and left click to exit the mode.

Requires nvidia-smi for displaying info and nvidia_settings for setting fan speed.

Configuration

Example

[[block]]
block = "nvidia_gpu"
interval = 1
format = " $icon GT 1030 $utilization $temperature $clocks "

Icons Used

•

gpu

TODO

•

Provide a mappings option similar to keyboard_layout’s to map GPU names to labels?

packages

Pending updates for different package manager like apt, pacman, etc.

Currently these package managers are available: - apt for Debian/Ubuntu based system - pacman for Arch based system - aur for Arch based system - dnf for Fedora based system

Configuration

Apt

Behind the scenes this uses apt, and in order to run it without root privileges i3status-rust will create its own package database in /tmp/i3rs-apt/ which may take up several MB or more. If you have a custom apt config then this block may not work as expected - in that case please open an issue.

Tip: You can grab the list of available updates using APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable

Pacman

Requires fakeroot to be installed (only required for pacman).

Tip: You can grab the list of available updates using fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/. If you have the CHECKUPDATES_DB env var set on your system then substitute that dir instead.

Note: pikaur may hang the whole block if there is no internet connectivity reference. In that case, try a different AUR helper.

Pacman hook

Tip: On Arch Linux you can setup a pacman hook to signal i3status-rs to update after packages have been upgraded, so you won’t have stale info in your pacman block.

In the block configuration, set signal = 1 (or other number if 1 is being used by some other block):

[[block]]
block = "packages"
signal = 1

Create /etc/pacman.d/hooks/i3status-rust.hook with the below contents:

[Trigger]
Operation = Upgrade
Type = Package
Target = *
[Action]
When = PostTransaction
Exec = /usr/bin/pkill -SIGRTMIN+1 i3status-rs

Example

Apt only config

[[block]]
block = "packages"
interval = 1800
package_manager = ["apt"]
format = " $icon $apt updates available"
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
### shows dmenu with cached available updates. Any dmenu alternative should also work.
button = "left"
cmd = "APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable | tail -n +2 | rofi -dmenu"
[[block.click]]
### Updates the block on right click
button = "right"
update = true

Pacman only config:

[[block]]
block = "packages"
package_manager = ["pacman"]
interval = 600
format = " $icon $pacman updates available "
format_singular = " $icon $pacman update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
### pop-up a menu showing the available updates. Replace wofi with your favourite menu command.
button = "left"
cmd = "fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/ | wofi --show dmenu"
[[block.click]]
### Updates the block on right click
button = "right"
update = true

Pacman and AUR helper config:

[[block]]
block = "packages"
package_manager = ["pacman", "aur"]
interval = 600
error_interval = 300
format = " $icon $pacman + $aur = $total updates available "
format_singular = " $icon $total update available "
format_up_to_date = " $icon system up to date "
### aur_command should output available updates to stdout (ie behave as echo -ne "update\n")
aur_command = "yay -Qua"

Dnf only config:

[[block]]
block = "packages"
package_manager = ["dnf"]
interval = 1800
format = " $icon $dnf.eng(w:1) updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
[[block.click]]
### shows dmenu with cached available updates. Any dmenu alternative should also work.
button = "left"
cmd = "dnf list -q --upgrades | tail -n +2 | rofi -dmenu"

Multiple package managers config:

Update the list of pending updates every thirty minutes (1800 seconds):

[[block]]
block = "packages"
package_manager = ["apt", "pacman", "aur","dnf"]
interval = 1800
format = " $icon $apt + $pacman + $aur + $dnf = $total updates available "
format_singular = " $icon One update available "
format_up_to_date = " $icon system up to date "
### If a linux update is available, but no ZFS package, it won't be possible to
### actually perform a system upgrade, so we show a warning.
warning_updates_regex = "(linux|linux-lts|linux-zen)"
### If ZFS is available, we know that we can and should do an upgrade, so we show
### the status as critical.
critical_updates_regex = "(zfs|zfs-lts)"

Icons Used

•

update

pacman

Pending updates available on pacman or an AUR helper.

Requires fakeroot to be installed (only required for pacman).

Tip: You can grab the list of available updates using fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/. If you have the CHECKUPDATES_DB env var set on your system then substitute that dir instead.

Note: pikaur may hang the whole block if there is no internet connectivity reference. In that case, try a different AUR helper.

Pacman hook

Tip: On Arch Linux you can setup a pacman hook to signal i3status-rs to update after packages have been upgraded, so you won’t have stale info in your pacman block.

In the block configuration, set signal = 1 (or other number if 1 is being used by some other block):

[[block]]
block = "pacman"
signal = 1

Create /etc/pacman.d/hooks/i3status-rust.hook with the below contents:

[Trigger]
Operation = Upgrade
Type = Package
Target = *
[Action]
When = PostTransaction
Exec = /usr/bin/pkill -SIGRTMIN+1 i3status-rs

Configuration

Examples

pacman only config:

[[block]]
block = "pacman"
interval = 600
format = " $icon $pacman updates available "
format_singular = " $icon $pacman update available "
format_up_to_date = " $icon system up to date "
critical_updates_regex = "(linux|linux-lts|linux-zen)"
[[block.click]]
### pop-up a menu showing the available updates. Replace wofi with your favourite menu command.
button = "left"
cmd = "fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/ | wofi --show dmenu"
[[block.click]]
### Updates the block on right click
button = "right"
update = true

pacman only config using warnings with ZFS modules:

[[block]]
block = "pacman"
interval = 600
format = " $icon $pacman updates available "
format_singular = " $icon $pacman update available "
format_up_to_date = " $icon system up to date "
### If a linux update is available, but no ZFS package, it won't be possible to
### actually perform a system upgrade, so we show a warning.
warning_updates_regex = "(linux|linux-lts|linux-zen)"
### If ZFS is available, we know that we can and should do an upgrade, so we show
### the status as critical.
critical_updates_regex = "(zfs|zfs-lts)"

pacman and AUR helper config:

[[block]]
block = "pacman"
interval = 600
error_interval = 300
format = " $icon $pacman + $aur = $both updates available "
format_singular = " $icon $both update available "
format_up_to_date = " $icon system up to date "
critical_updates_regex = "(linux|linux-lts|linux-zen)"
### aur_command should output available updates to stdout (ie behave as echo -ne "update\n")
aur_command = "yay -Qua"

Icons Used

•

update

pomodoro

A pomodoro timer

Technique

There are six steps in the original technique: 1) Decide on the task to be done. 2) Set the pomodoro timer (traditionally to 25 minutes). 3) Work on the task. 4) End work when the timer rings and put a checkmark on a piece of paper. 5) If you have fewer than four checkmarks, take a short break (3–5 minutes) and then return to step 2. 6) After four pomodoros, take a longer break (15–30 minutes), reset your checkmark count to zero, then go to step 1.

Configuration

Example

Use swaynag as a notifier:

[[block]]
block = "pomodoro"
notify_cmd = "swaynag -m '{msg}'"
blocking_cmd = true

Use notify-send as a notifier:

[[block]]
block = "pomodoro"
notify_cmd = "notify-send '{msg}'"
blocking_cmd = false

Icons Used

•

pomodoro

•

pomodoro_started

•

pomodoro_stopped

•

pomodoro_paused

•

pomodoro_break

TODO

•

Use different icons.

•

Use format strings.

privacy

Privacy Monitor

Configuration

pipewire Options (requires the pipewire feature to be enabled)

vl4 Options

Available Format Keys

You can use the suffixes noted above to get the following:

Available Actions

Example

[[block]]
block = "privacy"
[[block.driver]]
name = "v4l"
[[block.driver]]
name = "pipewire"
exclude_input = ["openrgb"]
display = "nickname"

Icons Used

•

microphone

•

volume

•

xrandr

•

webcam

•

unknown

rofication

The number of pending notifications in rofication-daemon

A different color is used if there are critical notifications.

Configuration

Example

[[block]]
block = "rofication"
interval = 1
socket_path = "/tmp/rofi_notification_daemon"
[[block.click]]
button = "left"
cmd = "rofication-gui"

Icons Used

•

bell

scratchpad

Scratchpad indicator

Configuration

Example

[[block]]
block = "scratchpad"

Icons Used

•

scratchpad

service_status

Display the status of a service

Right now only systemd is supported.

Configuration

Example

Example using an icon:

[[block]]
block = "service_status"
service = "cups"
active_format = " ^icon_tea "
inactive_format = " no ^icon_tea "

Example overriding the default inactive_state:

[[block]]
block = "service_status"
service = "shadow"
active_format = ""
inactive_format = " Integrity of password and group files failed "
inactive_state = "Warning"

sound

Volume level

This block displays the volume level (according to PulseAudio or ALSA). Right click to toggle mute, scroll to adjust volume.

Requires a PulseAudio installation or alsa-utils for ALSA.

Note that if you are using PulseAudio commands (such as pactl) to control your volume, you should select the "pulseaudio" (or "auto") driver to see volume changes that exceed 100%.

Configuration

Examples

Change the default scrolling step width to 3 percent:

[[block]]
block = "sound"
step_width = 3

Change the output name shown:

[[block]]
block = "sound"
format = " $icon $output_name{ $volume|} "
[block.mappings]
"alsa_output.usb-Harman_Multimedia_JBL_Pebbles_1.0.0-00.analog-stereo" = "Speakers"
"alsa_output.pci-0000_00_1b.0.analog-stereo" = "Headset"

Since the default value for the device_kind key is sink, to display microphone block you have to use the source value:

[[block]]
block = "sound"
driver = "pulseaudio"
device_kind = "source"

Display warning in block if microphone if using the wrong port:

[[block]]
block = "sound"
driver = "pulseaudio"
device_kind = "source"
format = " $icon { $volume|} {$active_port |}"
[block.active_port_mappings]
"analog-input-rear-mic" = "" # Mapping to an empty string makes `$active_port` absent
"analog-input-front-mic" = "ERR!"

Icons Used

•

microphone_muted (as a progression)

•

microphone (as a progression)

•

volume_muted (as a progression)

•

volume (as a progression)

•

headphones

speedtest

Ping, download, and upload speeds

This block which requires speedtest-cli.

Configuration

Example

Show only ping (with an icon)

[[block]]
block = "speedtest"
interval = 1800
format = " ^icon_ping $ping "

Hide ping and display speed in bytes per second each using 4 characters (without icons)

[[block]]
block = "speedtest"
interval = 1800
format = " $speed_down.eng(w:4,u:B) $speed_up(w:4,u:B) "

Icons Used

•

ping

•

net_down

•

net_up

taskwarrior

The number of tasks from the taskwarrior list

Clicking the right mouse button on the icon cycles the view of the block through the user’s filters.

Configuration

Example

In this example, block will be hidden if count is zero.

[[block]]
block = "taskwarrior"
interval = 60
format = " $icon count.eng(w:1) tasks "
format_singular = " $icon 1 task "
format_everything_done = ""
warning_threshold = 10
critical_threshold = 20
[[block.filters]]
name = "today"
filter = "+PENDING +OVERDUE or +DUETODAY"
[[block.filters]]
name = "some-project"
filter = "project:some-project +PENDING"

Icons Used

•

tasks

tea_timer

Timer

Configuration

time, hours, minutes, and seconds are unset when the timer is inactive.

hours, minutes, and seconds have been deprecated in favor of time.

Example

[[block]]
block = "tea_timer"
format = " $icon {$minutes:$seconds |}"
done_cmd = "notify-send 'Timer Finished'"

Icons Used

•

tea

temperature

The system temperature

This block displays the system temperature, based on libsensors library.

This block has two modes: “collapsed”, which uses only color as an indicator, and “expanded”, which shows the content of a format string. The average, minimum, and maximum temperatures are computed using all sensors displayed by sensors, or optionally filtered by chip and inputs.

Requires libsensors and appropriate kernel modules for your hardware.

Run sensors command to list available chips and inputs.

Note that the colour of the block is always determined by the maximum temperature across all sensors, not the average. You may need to keep this in mind if you have a misbehaving sensor.

Configuration

Note that when block is collapsed, no placeholders are provided.

Example

[[block]]
block = "temperature"
format = " $icon $max max "
format_alt = " $icon $min min, $max max, $average avg "
interval = 10
chip = "*-isa-*"

Icons Used

•

thermometer

time

The current time.

Configuration

Example

[[block]]
block = "time"
interval = 60
[block.format]
full = " $icon $timestamp.datetime(f:'%a %Y-%m-%d %R %Z', l:fr_BE) "
short = " $icon $timestamp.datetime(f:%R) "

Non Gregorian calendars

You can use calendars other than the Gregorian calendar by adding the calendar specifier in the locale string. When using this feature you can’t use chrono style format string, and you should use one of the options provided by the icu4x crate: short, medium, long, full.

** Only available using feature icu_calendar. **

Example

[[block]]
block = "time"
interval = 60
format = "$timestamp.datetime(locale:'fa_IR-u-ca-persian', f:'full')"

Icons Used

•

time

toggle

A Toggle block

You can add commands to be executed to disable the toggle (command_off), and to enable it (command_on). If these command exit with a non-zero status, the block will not be toggled and the block state will be changed to critical to give a visual warning of the failure. You also need to specify a command to determine the state of the toggle (command_state). When the command outputs nothing, the toggle is disabled, otherwise enabled. By specifying the interval property you can let the command_state be executed continuously.

To run those commands, the shell form $SHELL environment variable is used. If such variable is not presented, sh is used.

Configuration

Examples

This is what can be used to toggle an external monitor configuration:

[[block]]
block = "toggle"
format = " $icon 4k "
command_state = "xrandr | grep 'DP1 connected 38' | grep -v eDP1"
command_on = "~/.screenlayout/4kmon_default.sh"
command_off = "~/.screenlayout/builtin.sh"
interval = 5
state_on = "good"
state_off = "warning"

Icons Used

•

toggle_off

•

toggle_on

uptime

System’s uptime

This block displays system uptime in terms of two biggest units, so minutes and seconds, or hours and minutes or days and hours or weeks and days.

Configuration

text has been deprecated in favor of uptime.

Example

[[block]]
block = "uptime"
interval = 3600 # update every hour

Used Icons

•

uptime

vpn

Shows the current connection status for VPN networks

This widget toggles the connection on left click.

Configuration

Drivers

nordvpn

Behind the scenes the nordvpn driver uses the nordvpn command line binary. In order for this to work properly the binary should be executable without root privileges.

Mullvad

Behind the scenes the mullvad driver uses the mullvad command line binary. In order for this to work properly the binary should be executable and mullvad daemon should be running.

Example

Shows the current vpn network state:

[[block]]
block = "vpn"
driver = "nordvpn"
interval = 10
format_connected = "VPN: $icon "
format_disconnected = "VPN: $icon "
state_connected = "good"
state_disconnected = "warning"

Possible values for state_connected and state_disconnected:

warning
critical
good
info
idle

Icons Used

•

net_vpn

•

net_wired

•

net_down

•

country code flags (if supported by font)

Flags: They are not icons but unicode glyphs. You will need a font that includes them. Tested with: https://www.babelstone.co.uk/Fonts/Flags.html

watson

Watson statistics

Watson is a simple CLI time tracking application. This block will show the name of your current active project, tags and optionally recorded time. Clicking the widget will toggle the show_time variable dynamically.

Configuration

Example

[[block]]
block = "watson"
show_time = true
state_path = "~/.config/watson/state"

TODO

•

Extend functionality: start / stop watson using this block

weather

Current weather

This block displays local weather and temperature information. In order to use this block, you will need access to a supported weather API service. At the time of writing, OpenWeatherMap, met.no, and the US National Weather Service are supported.

Configuring this block requires configuring a weather service, which may require API keys and other parameters.

If using the autolocate feature, set the autolocate update interval such that you do not exceed ipapi.co’s free daily limit of 1000 hits. Or use autolocate_interval = "once" to only run on initialization.

Configuration

OpenWeatherMap Options

To use the service you will need a (free) API key.

One of coordinates, city_id, place, or zip is required. If more than one are supplied, coordinates takes precedence over city_id which takes precedence over place which takes precedence over zip.

The options api_key, city_id, place, zip, can be omitted from configuration, in which case they must be provided in the environment variables OPENWEATHERMAP_API_KEY, OPENWEATHERMAP_CITY_ID, OPENWEATHERMAP_PLACE, OPENWEATHERMAP_ZIP.

Forecasts are only fetched if forecast_hours > 0 and the format has keys related to forecast.

met.no Options

Met.no does not support location name, but if autolocate is enabled then autolocate’s city value is used.

US National Weather Service Options

Forecasts gather statistics from each hour between now and the forecast_hours value, and provide predicted weather at the set number of hours into the future.

Available Format Keys

You can use the suffixes noted above to get the following:

Example

Show detailed weather in San Francisco through the OpenWeatherMap service:

[[block]]
block = "weather"
format = " $icon $weather ($location) $temp, $wind m/s $direction "
format_alt = " $icon_ffin Forecast (9 hour avg) {$temp_favg ({$temp_fmin}-{$temp_fmax})|Unavailable} "
[block.service]
name = "openweathermap"
api_key = "XXX"
city_id = "5398563"
units = "metric"
forecast_hours = 9

Used Icons

•

weather_sun (when weather is reported as “Clear” during the day)

•

weather_moon (when weather is reported as “Clear” at night)

•

weather_clouds (when weather is reported as “Clouds” during the day)

•

weather_clouds_night (when weather is reported as “Clouds” at night)

•

weather_fog (when weather is reported as “Fog” or “Mist” during the day)

•

weather_fog_night (when weather is reported as “Fog” or “Mist” at night)

•

weather_rain (when weather is reported as “Rain” or “Drizzle” during the day)

•

weather_rain_night (when weather is reported as “Rain” or “Drizzle” at night)

•

weather_snow (when weather is reported as “Snow”)

•

weather_thunder (when weather is reported as “Thunderstorm” during the day)

•

weather_thunder_night (when weather is reported as “Thunderstorm” at night)

xrandr

X11 screen information

X11 screen information (name, brightness, resolution). With a click you can toggle through your active screens and with wheel up and down you can adjust the selected screens brightness. Regarding brightness control, xrandr changes the brightness of the display using gamma rather than changing the brightness in hardware, so if that is not desirable then consider using the backlight block instead.

NOTE: Some users report issues (e.g. here and here when using this block. The cause is currently unknown, however setting a higher update interval may help.

Configuration

Example

[[block]]
block = "xrandr"
format = " $icon $brightness $resolution "

Used Icons

•

xrandr

•

backlight

•

resolution

[1]

when using notification_count with the dunst driver use dunst > 1.9.0

Choosing your theme and icon set

To use a theme or icon set other than the default, add them to your configuration file like so:

[theme]
theme = "solarized-dark"
[icons]
icons = "awesome6"

Both the theme and icon set can be loaded from a separate file.

[theme]
theme = "<file>"
[icons]
icons = "<file>"

where <file> can be either a filename or a full path and will be checked in this order:

1.

If full absolute path given, then use it as is: /home/foo/custom_theme.toml

2.

If filename given, e.g. “custom_theme.toml”, then first check $XDG_CONFIG_HOME/i3status-rust/themes

3.

Then look for it in $XDG_DATA_HOME/i3status-rust/themes

4.

Otherwise look for it in /usr/share/i3status-rust/themes

Notes: - In case with icon sets, the file should be in the icons subdirectory instead of themes. - You can omit the .toml extension while specifying file parameters. - All the predefined themes are provided as files, so you use them as examples of how to write your own themes/icon sets.

Available themes

Note: screenshots were generated using this config with this swaybar config.

•

plain (default) [IMAGE: plain]

•

solarized-dark [IMAGE: solarized-dark]

•

solarized-light [IMAGE: solarized-light]

•

slick [IMAGE: slick]

•

modern [IMAGE: modern]

•

bad-wolf [IMAGE: bad-wolf]

•

gruvbox-light [IMAGE: gruvbox-light]

•

gruvbox-dark [IMAGE: gruvbox-dark]

•

space-villain [IMAGE: space-villain]

•

native (like plain with no background and native separators) [IMAGE: native]

•

semi-native (like native but with background) [IMAGE: semi-native]

•

nord-dark (polar night) [IMAGE: nord-dark]

•

dracula [IMAGE: dracula]

•

srcery [IMAGE: srcery]

•

ctp-frappe [IMAGE: ctp-frappe]

•

ctp-latte [IMAGE: ctp-latte]

•

ctp-macchiato [IMAGE: ctp-macchiato]

•

ctp-mocha [IMAGE: ctp-mocha]

Available icon sets

•

none (default. Uses text labels instead of icons)

•

awesome4 (Font Awesome 4.x)

•

awesome5 (Font Awesome 5.x)

•

awesome6 (Font Awesome 6.x)

•

emoji

•

material

•

material-nf (Any font from Nerd Fonts collection)

Note: In order to use the material icon set, you need a patched material icons font which can be found https://gist.github.com/draoncc/3c20d8d4262892ccd2e227eefeafa8ef/raw/3e6e12c213fba1ec28aaa26430c3606874754c30/MaterialIcons-Regular-for-inline.ttf here. Make sure to pass it in your i3 configuration bar block.

Overriding themes and icon sets

Create a block in the configuration called theme or icons like so:

[theme]
theme = "solarized-dark"
[theme.overrides]
# Example: redefine `idle` colors
idle_bg = "#123456"
idle_fg = "#abcdef"
# Example: swap `good` and `warning` colors
good_fg = { link = "warning_fg" }
good_bg = { link = "warning_bg" }
warning_fg = { link = "good_fg" }
warning_bg = { link = "good_bg" }
[icons]
icons = "awesome6"
[icons.overrides]
bat = [
    "| |",
    "|¼|",
    "|½|",
    "|¾|",
    "|X|",
]
bat_charging = "|^|"

Besides global overrides you may also use per-block overrides using the theme_overrides, icons_overrides and icons_format options available for all blocks. For example:

[[block]]
block = "cpu"
icons_format = "{icon}"
[block.theme_overrides]
idle_bg = "#123456"
idle_fg = "#abcdef"
[block.icons_overrides]
cpu_boost_on = "ON"
cpu_boost_off = "OFF"

Available theme overrides

All bg and fg overrides are html hex color codes like #000000 or #789ABC. A fourth byte for alpha (like #acbdef42) works on some systems. 00 is transparent, FF is opaque.

The tints are added to every second block counting from the right. They will therefore always brighten the block and never darken it. The alpha channel, if it works, can also be alternated in the same way.

Feel free to take a look at the provided color schemes for reference.

•

idle_bg

•

idle_fg

•

good_bg

•

good_fg

•

warning_bg

•

warning_fg

•

critical_bg

•

critical_fg

•

info_bg

•

info_fg

•

alternating_tint_bg

•

alternating_tint_fg

•

separator_bg

•

separator_fg

•

separator

•

end_separator

Available icon overrides

These can be directly set to a string containing the desired unicode codepoint(s) or use a TOML escape sequence like "\uf0f3" for up to 4-nibble codepoints and "\U0001f312" for up to 8-nibble codepoints.

You can find the codepoints in the documentation of the icon font you’re using.

Refer to individual block’s documentation for a list of used icons or provided icon sets for a complete list of icons.