i3bar Workspace Icons

This program leverages the i3bar workspace protocol to add icons corresponding to the windows in each workspace to the i3bar status bar (part of the i3 window manager).

Features

• Show a set number of window icons for each active, existing workspace
• Customize the icon spacing and icon limit per workspace

Requirements

• Python 3.13+
• i3 & i3bar v4.23+¹
• i3ipc-python v2.2.1+
• platformdirs v4.3.7+
• A Nerd Font patched font (highly recommended)

This program was tested on Debian GNU/Linux 13 (Trixie), but it should work on other Linux distributions as well.

Installation

Both pipx and uv can install Python programs from public Git repositories.

With pipx

pipx install git+https://github.com/vm70/i3bar-workspace-icons.git

With uv

uv tool install git+https://github.com/vm70/i3bar-workspace-icons.git

Usage

This program's primary use case is as a workspace command for i3bar. To set it up, modify your i3 configuration file (located in $HOME/.config/i3/config) to set i3bar's workspace_command option to i3bar-workspace-icons.

bar {
    # ...
    workspace_command i3bar-workspace-icons
    # ...
}

While it does have a command-line interface, it is not intended to be used directly except for debugging purposes or importing/exporting configurations.

usage: i3bar-workspace-icons [-h] [-V] [-d] [-D] [-c CONFIGFILES] [-n]

Workspace command for the i3 window manager that displays Nerd Font / Unicode
icons of windows inside each workspace.

options:
  -h, --help            show this help message and exit
  -V, --version         show the version number of this program and exit
  -d, --dump-config     dump the current configuration and exit
  -D, --debug           enable debug logging
  -c, --configfile CONFIGFILES
                        path to configuration files to use instead of the XDG
                        default
  -n, --dry-run         Run the program without connecting to i3 and exit

You shouldn't need to run this program directly in the terminal. Instead, set
it as the `workspace_command` in your i3bar configurtion.

Note

This program is incompatible with the Sway window manager. The i3bar workspace protocol does not have a corresponding Sway implementation. See Sway WM Issue #7419 for more information.

Configuration

This program has an internal default / reference INI configuration file located at src/i3bar_workspace_icons/default_config.ini.

Further customization can be done system-wide by creating a file at /etc/xdg/i3bar-workspace-icons/config.ini, or per-user in $XDG_CONFIG_HOME/i3bar-workspace-icons/config.ini.

To add custom icons, add a new section to the configuration file with the name of the window class. The value of the section should be a single character (or ligature) representing the icon to be used.

[window_classes]
my_program = 😊

Building from Source

This program can be built from source using Python's built-in venv module.

git clone https://github.com/vm70/i3bar-workspace-icons.git
cd i3bar-workspace-icons
python3 -m venv .venv --prompt=i3bar-workspace-icons
source .venv/bin/activate
pip install -e .

Special Thanks / Acknowledgments

• Michael Stapelberg & contributors, creator(s) of i3 and i3bar
• Tony Crisci, creator of i3ipc
• Tox Development Team, maintainer(s) of platformdirs

Similar Projects

• goi3autowname by Thomas Bellembois
• polybar-i3-windows by Jan Šeda
• i3-workspace-names-daemon by Chris Boddy

License

This program is not an official extension of i3 or i3bar. It is licensed under the 3-Clause BSD license. For more information, see LICENSE.

Footnotes

1. This is a hard requirement; the i3bar workspace protocol was introduced in i3 version 4.23. ↩