Configuring the i3 Window Manager


Why use the i3 window manager

If you’re a Linux user, you’re probably using a desktop environment that looks like Windows (e.g. KDE Plasma) or macOS (e.g. GNOME). But these desktop environments use a great deal of resources and are cumbersome when it comes to flexibility and navigation between applications and code. To solve these problems, most software developers and Linux/UNIX administrators install and use a tiling window manager.

While there are many different tiling window managers available, i3 is the most common one. It is easy to configure, and has great documentation available at

I’ve recently installed i3 on Asahi Linux (which is based on Arch Linux), and customized it for my developer workflow. In this post, I’ll walk through what I did. Once you install the appropriate packages using your Linux distribution’s package manager, the configuration steps are identical on any Linux distribution.

Installing i3

You can install i3 from your Linux distribution’s software repository. For Arch Linux, this would be sudo pacman -S i3-wm (you can instead use sudo pacman -S i3-gaps to install an extended version of i3 that has more features).

Next, you’ll be able to choose i3 instead of your KDE or GNOME desktop from the display manager (login screen) menu the next time you log into a graphical desktop. After logging into i3 for the first time, you must press Enter to generate the i3 configuration file (~/.config/i3/config), and then choose whether the Alt key or the Windows key (=Command key on a Mac) will be used as the mod key. The mod key is the key you press alongside other keys to perform functions in i3.

Basic i3 navigation and usage

When you’re in i3, you should first take some time to experiment with the following key combinations, as well as experiment with how your mouse can be used to change focus between tiles:

  • mod+Enter opens a Terminal (additional Terminals are split horizontally on the screen)
  • mod+v ensures that the next Terminal opened (using mod+Enter) will be split vertically on the screen
  • mod+cursor_keys navigates between open Terminal windows on the screen (you can use j/k/l/; instead of cursor keys)
  • mod+Shift+q closes the current Terminal
  • mod+d opens the dmenu application launcher (where you can type the name of graphical programs to open)
  • mod+s switches to stacking window mode
  • mod+e switches to tiling window mode (the default)
  • mod+r enters resize mode (where you can use the cursor keys to resize the window)
  • mod+Shift+cursor_keys moves the current window to another area of the screen
  • mod+Shift+2 moves the current window to workspace #2 (workspace 1-10 are available, with 0 on your keyboard representing workspace 10)
  • mod+2 switches to workspace #2
  • mod+Shift+e logs out of i3
  • mod+Shift+r restarts i3 (commonly done after changing ~/.config/i3/config)

Some common graphical programs that I like to start on their own workspace using mod+d include:


Basic i3 customization

There are many different basic customizations that you’ll probably want to do to i3, including setting a background wallpaper, changing display settings, and configuring a screen lock.

To set your background wallpaper using the feh command, edit ~/.config/i3/config and add this line to the bottom:

exec_always feh --bg-scale "/path/to/wallpaper/file"

To configure display settings (including for multiple displays), you run the graphical arandr command. Alternatively, to lock your screen, you can use the i3lock command. You can create a mod key combination for locking your screen by editing your i3 configuration file. For example, to lock your screen using mod+Shift+x with a wallpaper of your choice, you can add the following line to your ~/.config/i3/config file:

bindsym $mod+shift+x exec i3lock --image "/path/to/wallpaper/file"

If the feh, arandr or i3lock commands do not work, you’ll likely need to install them first from your Linux distribution’s software repository (e.g. sudo pacman -S feh arandr i3lock on Arch Linux).

Customizing your workspaces

To customize the names of your workspaces, you can modify the following section in your ~/.config/i3/config file. My customizations are shown here:

# We use variables to avoid repeating the names in multiple places.
set $ws1 "1: Terminals"
set $ws2 "2: Firefox"
set $ws3 "3: Performance"
set $ws4 "4: Weather"
set $ws5 "5: File browser"
set $ws6 "6: K3S"
set $ws7 "7: Git log"
set $ws8 "8: Tetris"
set $ws9 "9: Email"
set $ws10 "10: Slack"

I prefer to replace the words shown next to each number (e.g. Terminals) with an icon that represents the same thing. If you install Font Awesome, you can paste in icons into the double-quoted set sections above. To do this, go to, enter the webfonts folder, and download each of the .ttl files within to your ~/.fonts directory (you’ll likely need to create this directory first). Now that the fonts are installed on your system, log out and into i3 again, go to, copy the actual icon you want (to the left of the icon name), and then paste it into a double-quoted set section shown earlier. Log out and into i3 again and you’ll see the icon.

To automatically start certain graphical apps on certain workspaces each time you log into i3, you can add commands to the bottom of your ~/.config/i3/config file. For example, the following lines would start the relevant apps on the first 5 workspaces shown earlier:

exec --no-startup-id i3-msg 'workspace $ws1; exec gnome-terminal'
exec --no-startup-id i3-msg 'workspace $ws2; exec firefox'
exec --no-startup-id i3-msg 'workspace $ws3; exec gnome-system-monitor'
exec --no-startup-id i3-msg 'workspace $ws4; exec gnome-weather'
exec --no-startup-id i3-msg 'workspace $ws5; exec nautilus; workspace $ws1'

Customizing window border and title colors

Unless you’re a big fan of the defaults (or lazy), you’ll want to customize the default colors used by the various parts of the i3 desktop, including the bar and window borders. To do this, add the following lines just before the bar section of your ~/.config/i3/config file:

###Color variables
set $bg-color #2f343f
set $inactive-bg-color #2f343f
set $text-color #f3f4f5
set $inactive-text-color #676E7D
set $urgent-bg-color #E53935

###Window colors  
###Fields: identifier border background text indicator
client.focused  $bg-color $bg-color $text-color #ff0000
client.unfocused  $inactive-bg-color $inactive-bg-color $inactive-text-color #ff0000
client.focused_inactive  $inactive-bg-color $inactive-bg-color $inactive-text-color #ff0000
client.urgent  $urgent-bg-color $urgent-bg-color $text-color #ff0000

You can modify the hexadecimal RGB values to your liking, of course. I used red (#ff0000) for any status indicators (placeholders for new windows) and urgent status indicators (alerts) to match my darkblood Zsh theme, and grey (#2f343f) for backgrounds to match the most common color in my wallpaper.

Customizing the bar colors and position

If you’ve modified your window colors, you’ll also want to modify the i3 bar colors to match. Most users (myself included) also prefer to move the bar to the top of the screen. To do all of this, you can modify the following lines within the bar section of your ~/.config/i3/config file:

bar {
    status_command i3status
    position top
    colors {
        background $bg-color
        separator #757575
        ###Fields: identifier border background text indicator
        focused_workspace $bg-color $bg-color $text-color
        inactive_workspace $inactive-bg-color $inactive-bg-color $inactive-text-color
        urgent_workspace $urgent-bg-color $urgent-bg-color $text-color

Customizing the system font and font size

While the default font used in i3 is pretty drab, you can easily replace it with something better, such as San Francisco. You can download the .zip of this font from and then copy the four .ttf files within to your ~/.fonts directory. Next, modify the following font pango: line in your ~/.config/i3/config file to reflect the name of the new font, as well as specify a size (I prefer font size 16 on a large monitor):

font pango:System San Francisco Display 16

Customizing the font, window and icon theme used by programs

The graphical programs you run are often created using the GIMP Toolkit (GTK). To use the same font earlier with the GTK, edit your ~/.gtkrc-2.0, ~/.config/gtk-3.0/settings.ini and ~/.config/gtk-4.0/settings.ini files, and and modify the following line to reflect your new font (it’s good to use a slightly smaller font size than your system font - e.g., 13):

gtk-font-name="System San Francisco Display 13"

Alternatively, you can run the lxappearance graphical tool to modify your GTK font to San Francisco. You may need to install this tool first from your Linux distribution’s software repository (e.g. sudo pacman -S lxappearance on Arch Linux).

The lxappearance tool can also be used to modify your window and icon themes as well. But you’ll need to install those themes first. There are many themes to choose from, and I recommend you install all that are listed in your Linux distribution’s software repository to see which ones you like best.

The Arc Dark GTK theme is quite popular and the one I use. On Arch Linux, you can install this them using the sudo pacman -S arc-gtk-theme command. I also prefer the Faenza icon theme, which can be installed using sudo pacman -S faenza-icon-theme on Arch Linux. Next, you can choose to apply the Arc Dark GTK theme and Faenza icon theme using the lxappearance tool and restart i3 to see your changes.

Many GTK themes also have an equivalent Firefox theme. Thus, if you use Arc Dark as your GTK theme, be sure to navigate to the themes configuration within Firefox, and then search for and install Arc Dark to ensure that Firefox matches the rest of your desktop.

Replacing the Dmenu application launcher with Rofi

The default Dmenu application launcher is pretty basic. As a result, most i3 users replace it with Rofi. You must first install Rofi (e.g. sudo pacman -S rofi on Arch Linux), and then edit the line for the mod+d mapping within your ~/.config/i3/config file as follows:

bindsym $mod+d exec "rofi -modi drun,run -show drun"

Now, when you use mod+d, you’ll get a much nicer application launcher in the middle of your screen that looks far better.

Configuring the elements on your bar

The components on the right side of your bar are generated by a command. By default, this command is i3status but can be changed to i3blocks for easy customization. After installing i3blocks using your Linux distribution’s software repository (e.g. sudo pacman -S i3blocks on Arch Linux), you can modify the status_command line under the bar section in your ~/.config/i3/config file to read:

status_command i3blocks

Next, you can copy the default i3blocks configuration to your home directory using the following commands:

mkdir ~/.config/i3blocks
cp /etc/i3blocks.conf ~/.config/i3blocks/config

Now, you can edit the easy-to-read paragraphs in the ~/.config/i3blocks/config file to choose which sections, text and colors you want. There are many sample paragraphs you can copy into this file from (as well as great documentation). You can even paste icons from into these paragraphs to place icons in your bar that represent functions and status.

If you followed what I did in this blog post, you should have an i3 configuration that is similar to mine. Here are some screenshots of what I have on different workspaces:

i3 workspace1

i3 workspace2

i3 workspace3

i3 workspace5