Introduction to i3

i3 is a tilling window manager. It is dynamic, fast, and an addictive environment. I have been using it for last 6 months. Once the initial hiccup is dealt with it becomes natural to you and the way you do computing. In this tutorial I will try to explain the basics and help you getting started with i3.

Since you will eventually be picking up the software you like to use with i3, I am not going to give you a comprehensive list. However, I recommend you install packages like i3-wm, i3lock, i3status, dmenu, rxvt-unicode/urxvt, scrot, xdotool, xclip and feh. I am sure finding these tools in your distribution’s software repository should not be a problem. When you start, i3 will suggest you to copy the config file to your home directory. It will also suggest default mode key. Select Super/Win key as the default modifier. If you have already selected Alt as the mod key, you can change it in ~/.i3/config to Mod4. There are many GUI applications that use Alt as key combination for different operations. Therefore, I suggest you choose Mod4 (Super/Win).

Initial screenshot

Learn the basics
Before you start, download this reference card and learn the basic keyboard shortcuts. You can also see the most important ones in the man page (man i3). Here are some of the keys, I use on daily basis.

$mod + Enter = Open a new terminal
$mod + j/k/l/; = Move between open windows (+ Shift to move windows)
$mod + e/s/w = Switch between tilling, stacking and tabbed interfaces
$mod + f = Toggle fullscreen
$mod + d = Open dmenu to open applications
$mod + Shift + q = Close an application
$mod + v/h = Instruct i3, where next opened window will will go (vertical/horizontal)
$mod + 1-9 = Switch workspaces (+ Shift to move windows)
$mod + Shift + r = Restart i3 (after you change config file)
$mod + Shift + e = Exit i3
$mod + Shift + Space = Float a tilled window
$mod + left/right mouse button = Drag and resize floating windows

Learn to use i3
Tilling mode is not good for all tasks, therefore you need to mix other modes as well (at least in the beginning). For example, if you are editing/referencing 5 or 6 files in libreoffice use tabbed interface instead of tilling. I suggest you also keep a lightweight environment like blackbox or lxde, until you are comfortable with i3.

One aspect of learning i3 comes from the ability to configure it to your liking. It has very easy and logical configuration file. If you mix that with their user guide, you will feel a lot confident learning how this window manager works. If you want to see some examples to configure i3, you can use the man page (man i3). In the following sections, I will show bits and pieces of settings you might want to try.

a. Basics

Open up ~/.i3/config file and add following commands.

# scratchpad
bindsym $mod+Shift+minus move scratchpad
bindsym $mod+minus scratchpad show
# Toggle movement
bindsym $mod+a workspace back_and_forth
bindsym $mod+Shift+a move container to workspace back_and_forth
bindsym $mod+n workspace next
bindsym $mod+p workspace prev

Note: Since we are using $mod+a to switch between workspaces, you need to change the focus parent setting to something else (e.g $mod + b).

# focus the parent container
bindsym $mod+b focus parent

To reflect the changes, you need to press “Super + Shift + r” key combination. If something goes wrong, i3 lets you know through an error message. Since, it is easy to configure and see these changes without restarting the client, I suggest you do changes incrementally. The second section (Toggle movement), of above configuration is self explanatory. As for the first, you need to understand the concept of scratchpad. Scratchpad lets you hide open applications. For example, if you open up a text document by clicking the file icon in nautilus, in accordance to the tilling window manager, it takes one half of the screen. If you feel nautilus is a nuisance in this situation, you can hide nautilus by pressing “Super + Shift + –“, when it is in focus. This might be useful in situations where you need to compare two documents, and don’t want the workspace to be taken by other applications. If you need to bring back applications from scratch, you can press “Super + –“. These applications will open in floating mode. Therefore, to move it back to tilling mode, you can press “Super + Shift + Space” keys.

b. Giving name to workspace.

# switch to workspace
bindsym $mod+5 workspace 5:web
# move focused container to workspace
bindsym $mod+Shift+5 move container to workspace 5:web

You can give different names to workspaces. In fact, the naming scheme is very flexible e.g 5:web is different than 5 or web (as long as you bind different keys to different workspaces).

c. Status bar

bar {
 status_command i3status

This is the section, you need to change to change the layout and color of the status bar. If you need to change contents displayed in the status bar, you need to configure ~/.i3status.conf file as well. Use the example in i3status man page (man i3status) or copy /etc/i3status.conf to ~/.i3status.conf and change it. As for the changes in ~/.i3/config file, configure it to something like the following.

bar {
 status_command i3status
 position top
 #font -misc-fixed-medium-r-normal--8-120-75-75-C-70-iso10646-1
 font pango:DejaVu Sans Mono, Ionicons, FontAwesome 8
 colors {
 background #000000
 statusline #33aaff
 focused_workspace #11aaff #005500
 active_workspace #11aaff #005500
 urgent_workspace #ffffff #990000

d. Changing border color of windows.

Add this to ~/.i3/config.

new_window pixel 1
new_float pixel 1
hide_edge_borders both
# class border backgr indicator
client.focused #9fbc00 #9fbc00 #111111
client.unfocused #444444 #444444 #315858
client.focused_inactive #444444 #444444 #2c2c2f
client.urgent #383a3b #383a3b #ee0000

e. Keyboard shortcuts

This is the section, you will edit the most before settling for a setting you like.

i. Multimedia

Since I use ncmpcpp MPD client as my default music player, I use following settings to control it.

bindsym XF86AudioRaiseVolume exec pactl set-sink-volume 0 +5%
bindsym XF86AudioLowerVolume exec pactl set-sink-volume 0 -- -5%
bindsym XF86AudioMute exec pactl set-sink-mute 0 toggle
bindsym XF86AudioPlay exec ncmpcpp toggle
bindsym XF86AudioStop exec ncmpcpp stop
bindsym XF86AudioPrev exec ncmpcpp prev
bindsym XF86AudioNext exec ncmpcpp next

You have to install pactl to change the volume. As you might have guessed from above commands, if your favorite music player accepts command line parameters, it is easy to bind them to multimedia keys in your keyboard.

ii. Alternate keys

You might want to bind Alt + q or Win + q as well to quit an application. To lock the window you can use i3lock (use -d to turn off the display).

bindsym $mod+q kill
bindsym Mod1+q kill
bindsym $mod+Control+l exec i3lock -d

iii. Scripts

If you want to open lets say feedly web site using a shortcut, you can use settings like this in the configuration file.

bindsym $mod+Control+f exec ~/bin/

This is the content of the script file.

#chromium ''
xdg-open ''

Make this script executable (chmod +x ~/bin/ Here xdg-open opens the default browser. In case, you want to associate dedicated browser (in this case chromium), you can do so using the first line instead of second one.

iv. Favorite applications

Some of my favorite keyboard combination to open applications are as follows

bindsym $mod+Control+x exec firefox
bindsym $mod+Control+c exec chromium
bindsym $mod+x exec nautilus
bindsym $mod+Control+k exec keepassx
bindsym $mod+Control+3 exec "transmission-remote --alt-speed"

f. Startup Applications

To start applications at startup you can use commands similar to these.

exec /usr/bin/nm-applet
exec /usr/bin/pasystray
exec --no-startup-id exec mpd
exec --no-startup-id sh ~/.fehbg

I use feh to set default background. Content of ~/.fehbg is as follows.

feh --bg-fill '/home/username/Pictures/anime1.jpg'


Use gtk-theme-switch2 application to change gtk theme. If you are using lxde based applications, use lxappearance. You can also create ~/.config/gtk-3.0/settings.ini file to change some settings. I suggest, you explore theming once you get used to the basics of i3.


Explore things like clipboard management with xclip, setting up urxvt instead of i3-sensible-terminal.  As commented in dmenu section, you can also install i3-dmenu-desktop to only show GUI applications. If you need a reference on how to configure some of these applications you can look at the setting files I use. I hope, I have provided enough information for you to play with i3. If you learn by watching, I suggest you watch this video by gotbletu.



Filed under Uncategorized

5 responses to “Introduction to i3

  1. tom

    Nice tutorial! I may have to add the section on customizing the i3status bar to mine (

  2. Love the posting ! Been wanting to test drive a tiling window manager. You left some good features for me to read up and learn. Will give i3 a go !! Thx

  3. Which wallpaper is that? It looks great!

  4. Thanks man. Nice and easy…skipped the user guide, this helped me better.

Leave a Reply to Alper Cinar Cancel reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s