# i3

Related articles

- Desktop environment
- Display manager
- File manager functionality
- Window manager
- Comparison of Tiling Window Managers
- Clipboard
- Autostarting#Graphical

i3 is a dynamic tiling window manager inspired by wmii that is primarily targeted at developers and advanced users.

Clients (windows) are organized in a tree data structure within containers. The tree branches via horizontal or vertical splits, and containers can also be set to tabbed or stacked layouts. Floating windows are available for corner cases that don't mix well with tiling, and remain on a separate layer above the tiled windows.

## Installation

Install the i3 package group from the official repositories, which includes: i3-wm, the window manager; i3status, a package to write a status line to i3bar through stdout; and i3lock, an improved screenlocker.

Additional packages are available in the Arch User Repository, including the development version i3-git. In many cases, bugs are fixed in the development version and upstream will ask to reproduce any errors with this version.[1]

Install i3-gnome to add GNOME and X-sessions with i3 running as the window manager. An Xsession starting just the window manager is included in i3.

## Run i3 from xinitrc

Edit your `~/.xinitrc` and add:

    exec i3

Now you can start i3 by running `startx` from a tty.

If you want i3 to log its output (useful for debugging), add this line to `~/.xinitrc`:

    exec i3 -V >> ~/.i3/i3log 2>&1

If you use the Nvidia binary driver <302.17 you need to add the `--force-xinerama` flag to `~/.xinitrc`. A detailed explanation can be found at i3wm.org.

    exec i3 --force-xinerama

If you have trouble with mapping keys (ie ; as semicolon), use xorg-xev or see Extra Keyboard Keys.

    $ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'

## Usage

See the official documentation on this subject for more information: i3 User’s Guide

In i3, commands are invoked using a modifier key, which is referred to as `$mod`. This is the Alt key (Mod1) by default, with the Windows key (Mod4) being a popular alternative.

### Default keybindings

Key | Command
--- | ---
$mod + Enter | Open terminal
$mod + A | Focus Parent
$mod + S | Stacked Layout
$mod + W | Tabbed Layout
$mod + E | Default Layout
$mod + SpaceBar | Focus tiling/floating
$mod + D | dmenu
$mod + H | Split Horizontal
$mod + V | Split Vertically
$mod + J | Left
$mod + K | Down
$mod + L | Up
$mod + ; | Right
$mod + Shift + Q | Kill window
$mod + Shift + E | Exit i3
$mod + Shift + C | Reload i3config without restarting
$mod + Shift + R | Restart i3 (reloads i3config without exiting i3)
$mod + Shift + J | Move left
$mod + Shift + K | Move down
$mod + Shift + L | Move up
$mod + Shift + : | Move right
$mod + Shift + SpaceBar | Toggle tiling/floating

### Application launcher

i3 currently uses dmenu as a application launcher, which is bound by default to `$mod+d`.

Alternatively, you can use i3-dmenu-desktop, which creates a list of all installed applications via their .desktop files. There is a rewrite of this perl script in C called j4-dmenu-desktop-git, which is a near-drop-in replacement for the script shipped with i3, but much faster.

## Configuration

#### i3bar

In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:

    ~/.i3/config

    bar {
        output            LVDS1
        status_command    i3status
        position          top
        mode              hide
        workspace_buttons yes
        tray_output       none

        font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1

        colors {
            background #000000
            statusline #ffffff

            focused_workspace  #ffffff #285577
            active_workspace   #ffffff #333333
            inactive_workspace #888888 #222222
            urgent_workspace   #ffffff #900000
        }
    }

For further information see the Configuring i3bar section of the official User Guide.

### i3status

First we need to copy over the default configuration files that we will be working with to our home directory.

    $ cp /etc/i3status.conf ~/.i3status.conf

Note that not all plugins are defined in the default config, see `man 1 i3status`

Tip: The example configuration file uses `eth0` and `wlan0` as interface names, see Network configuration#Device names if they do not match with your system.

#### i3status replacements

conky — Highly extensible system monitor. For usage with i3bar see this tutorial

  http://conky.sourceforge.net/ || conky

i3blocks — Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.

  https://github.com/vivien/i3blocks || i3blocks

i3cat — A simple and flexible program which concatenates i3bar blocks from multiple sources (scripts, i3status, etc.). Handles click events, multiple blocks from one script and signal forwarding to its subprocesses.

  http://vincent-petithory.github.io/i3cat/ || i3cat-git

i3pystatus — Extensible Python 3 status bar with many plugins and configuration options by default.

  https://github.com/enkore/i3pystatus i3pystatus || i3pystatus-git

i3situation — Another Python 3 status bar generator.

  https://github.com/HarveyHunt/i3situation || i3situation-git

j4status — Provides a statusline, configurable via plugins, and written in C.

  http://j4status.j4tools.org/ || j4status-git

#### i3status wrappers

h2status — Bash wrapper for i3status that allows custom json entries as input, and can handle click events as well as asynchronous updates of the status bar.

  https://wiki.archlinux.org/index.php/H2status || h2status

py3status — An extensible i3status wrapper written in python.

  https://github.com/ultrabug/py3status || py3status

#### i3bar alternatives

Some users may prefer panels such as those provided by conventional Desktop Environments. This can be achieved within i3 by launching the panel application of choice during startup.

For the XFCE panel, add the following line anywhere in `~/.i3/config`:

    exec --no-startup-id xfce4-panel

Alternatively if using `startx`, this can be done in `~/.xinitrc`

    xfce4-panel &

Note: Panel features that are specific to the Desktop Environment (e.g., widgets for managing workspaces/sessions) will most likely not work, though i3's functionality should remain unaffected.

i3bar can be disabled by commenting out the `bar{ }` section of `~/.i3/config`.

#### Iconic fonts in the status bar

There is a patch for i3bar to make it properly support icons, but here we'll see how to take advantage of a couple of complete iconic font sets in order to get monochromatic icons in your status bar. Some ttf iconic font sets that are currently available in the AUR are:

- ttf-font-awesome that has a cheatsheet showing the Unicode point for each glyph here [2].
- ttf-font-icons provides the Icons font set, a non-overlapping and consistently sized mix of Awesome and Ionicons. This not only avoids the overlapping between Awesome and Ionicons but also some minor overlapping between the usual DejaVu Sans and Awesome. All in all it provides a ready to use solution for your status bar including lots of icons. The cheatsheet is here [3].

Then you can combine these fonts by defining a font fallback sequence in your `~/.i3/config`:

    bar {
      ...
      font pango:DejaVu Sans Mono, Icons 8
      ...
    }

Notice that you have to first list the comma separated font families and then add only one size specification at the end of the string. Don't set a size for each family (even if it happens to be the same size for every family) and don't try to get the same result using multiple font directives, as the vertical alignments and heights of the different components of the i3bar will be wrong in unexpected ways. The correct pango descriptor syntax is as shown above.

Finally, you will have to enter the iconic glyphs into the format strings in `~/.i3status.conf`. For this, use the unicode numbers given in the cheatsheets linked above. For example, if you're using vim while in insert mode you can type <C-v>uXXXX, where XXXX is the unicode hexadecimal number for the glyph.

### Quickly jumping to open window

- quickswitch-i3 — Python utility to quickly change to and locate windows in i3

  https://github.com/proxypoke/quickswitch-for-i3 || quickswitch-i3

- i3-wm-scripts — search for and jump to windows with particular names matching regexp

  https://github.com/yiuin/i3-wm-scripts ||

- winmenupy — Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.

  https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py ||

### Workspace names

Although not required, many prefer to name frequently used workspaces. Add your workspace names to `~/.i3/config`, by modifying the corresponding lines to switch workspaces as well as move focused containers to those workspaces.

    # switch to workspace
    bindsym $mod+1 workspace 1:Web
    bindsym $mod+2 workspace 2:Mail
    bindsym $mod+3 workspace 3:Irc
    bindsym $mod+4 workspace 4:Shell

    # move focused container to workspace
    bindsym $mod+Shift+1 move container to workspace 1:Web
    bindsym $mod+Shift+2 move container to workspace 2:Mail
    bindsym $mod+Shift+3 move container to workspace 3:Irc
    bindsym $mod+Shift+4 move container to workspace 4:Shell

When using multiple monitors, you also need to determine which monitor workspaces open to. `xrandr` will show available display ports. Some common ones are LVDS1 for laptops, or VGA1, HDMI1, HDMI2, etc. for external monitors. If you are using Xinerama use the outputs xinerama-0, xinerama-1, etc. instead.

    # Workspace names
    workspace "1:Web" output LVDS1
    workspace "2:Mail" output LVDS1
    workspace "3:Irc" output LVDS1
    workspace "4:Shell" output LVDS1

### Launching programs on specific workspaces

To maximize efficiency you can setup certain programs to automatically launch to a specific workspace. This can be accomplished one of two ways. You could use the `assign` command so when you manually launch a program it is directed to a the workspace you assigned. An example would be:

    # Assign URxvt terminals to workspace 2
    assign [class="URxvt"] 2

Or if you have renamed the workspaces like the above examples then you must set the new workspace name instead of the number:

    # Assign URxvt terminals to workspace 4:Shell
    assign [class="URxvt"] 4:Shell

Note: To be able to determine the class, title, instance, etc of an open window you can use the tool `xprop` by installing the package xorg-xprop from the Extra repository.

Alternatively you can change to your target workspace with `i3-msg` then have your frequently used programs start automatically with the `exec` command:

    exec --no-startup-id i3-msg 'workspace 1:Web; exec /usr/bin/firefox'
    exec --no-startup-id i3-msg 'workspace 2:Mail; exec urxvt -name Mail -e /usr/bin/mutt'
    exec --no-startup-id i3-msg 'workspace 3:Irc; exec /usr/bin/urxvt -name irssi -e /usr/bin/irssi'
    exec --no-startup-id i3-msg 'workspace 4:Shell; exec /usr/bin/urxvt'

### Tabbed or stacked web-browsing

Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.

To let i3 manage your tab-less web-browser, in this example for uzbl, add the following line to your `~/.i3/config`

    for_window [class="Uzbl-core"] focus child, layout stacking, focus

This is for stacked web browsing, meaning that the windows will be shown vertically. The advantage over tabbed browsing is that the window-titles are fully visible, even if a lot of browser windows are open.

If you prefer tabbed browsing, with windows in horizontal direction ('tabs'), use

    for_window [class="Uzbl-core"] focus child, layout tabbed, focus

### Terminal emulator

By default when you press `$mod+Return` it launches the `i3-sensible-terminal` which is a script that invokes a terminal. It attempts to start one of these terminals in the following order:

- `$TERMINAL`
- urxvt
- rxvt
- terminator
- Eterm
- aterm
- xterm
- gnome-terminal
- roxterm
- xfce4-terminal

You can force it to launch your terminal of choice by modifying this line

    bindsym $mod+Return exec i3-sensible-terminal

Alternatively, locally define the `$TERMINAL` variable:

    $ export TERMINAL=yourterminal

### Scratchpad

A scratchpad to quickly jot down or paste notes is very handy! i3 has a feature that allows moving windows to a scratchpad workspace. This workspace will be hidden from view until recalled with the `scratchpad show` command.

To send a focused window to the scratchpad with `$mod+Shift+minus` and recall it with `$mod+minus`, add these lines to `~/.i3/config`

    # Make the currently focused window a scratchpad
    bindsym $mod+Shift+minus move scratchpad

    # Show the first scratchpad window
    bindsym $mod+minus scratchpad show

You can start your favorite editor on startup and have it automatically moved to the scratchpad workspace for quick recall. The following example in `~/.i3/config` starts the urxvt terminal, have it launch the nano editor, and then moves it to the scratchpad:

    # starting a specially named term automatically
    exec --no-startup-id urxvt -name scratchpad -e /usr/bin/nano

    # move this to scratchpad, if active
    for_window [class="URxvt" instance="scratchpad"] move scratchpad

To setup multiple scratchpads, see FAQ.

### Colorschemes

The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.

- i3-style — Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme

  https://github.com/acrisci/i3-style || nodejs-i3-style

- j4-make-config — Merge your config with provided themes or personal config parts, for example host-specific configuration, allowing flexible and dynamic customization of the configuration

  https://github.com/okraits/j4-make-config || j4-make-config-git

### Shutdown, reboot, lock screen

As there are no Shutdown, Reboot, or Lock Screen buttons, we can add some hotkey combinations to help us out. First we need to create this script and save it as `i3exit`. Remember to make it executable with `chmod +x` and to place it somewhere in your `$PATH`. This script assumes that you have polkit installed to allow unprivileged users to run power management commands.

    #!/bin/sh
    lock() {
        i3lock
    }

    case "$1" in
        lock)
            lock
            ;;
        logout)
            i3-msg exit
            ;;
        suspend)
            lock && systemctl suspend
            ;;
        hibernate)
            lock && systemctl hibernate
            ;;
        reboot)
            systemctl reboot
            ;;
        shutdown)
            systemctl poweroff
            ;;
        *)
            echo "Usage: $0 {lock|logout|suspend|hibernate|reboot|shutdown}"
            exit 2
    esac

    exit 0

Now add the following lines to your `~/.i3/config` Once completed you will be presented with a prompt whenever you press `$mod+pause`.

    set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown
    mode "$mode_system" {
        bindsym l exec --no-startup-id i3exit lock, mode "default"
        bindsym e exec --no-startup-id i3exit logout, mode "default"
        bindsym s exec --no-startup-id i3exit suspend, mode "default"
        bindsym h exec --no-startup-id i3exit hibernate, mode "default"
        bindsym r exec --no-startup-id i3exit reboot, mode "default"
        bindsym Shift+s exec --no-startup-id i3exit shutdown, mode "default"

        # back to normal: Enter or Escape
        bindsym Return mode "default"
        bindsym Escape mode "default"
    }
    bindsym $mod+Pause mode "$mode_system"

For a list of alternative screen lockers, see List of applications/Security#Screen lockers.

### Screensaver and power management

You can use DPMS to blank your screen or to suspend/poweroff your monitor. Adding the following line to your `~/.i3/config` will suspend your monitor after 10 minutes.

    exec --no-startup-id xset dpms 600

With xss-lock you can register a screenlocker for your i3 session. xss-lock subscribes to the systemd-events `suspend`, `hibernate`, `lock-session`, and `unlock-session` with appropriate actions (run locker and wait for user to unlock or kill locker). It also reacts to the X screensaver and runs or kills the locker in response to the x-server signals. Start xss-lock in your autostart like this:

    xss-lock -- i3lock -i background_image &

### Save the current session

Install i3session-git from the AUR to save and restore sessions.

## Patched packages

Packages with patches not merged upstream are available in the AUR:

i3-git-overlap-docks — Overlapping dock for stand-alone tray

  || i3-git-overlap-docks

i3-mouse-close — Middle-click close support

  https://faq.i3wm.org/question/550/manipulating-windows-with-the-mouse || i3-mouse-close

i3-smart-border — Smart borders

  https://github.com/ashinkarov/i3-extras || i3-smart-border

i3-wm-iconpatch — Titlebar icon support

  || i3-wm-iconpatch

## Troubleshooting

### Mouse cursor remains in waiting mode

When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.

To solve this for a particlar application, use the `--no-startup-id` parameter, for example:

    exec --no-startup-id ~/script
    bindsym $mod+d exec --no-startup-id dmenu_run

To disable this animation globally, see Cursor_Themes#Create_links_to_missing_cursors.

### Tearing

i3 does not properly implement double buffering hence tearing or flickering may occur. In case of problems, try using a composite manager.

### Buttons in the i3 message bar do not work

Buttons such as "Edit config" in `i3-msg` call `i3-sensible-terminal`; make sure your Terminal emulator is recognized by i3.

## See also

- Official website
- funtoo Wiki
- i3 Source code
- i3 Window Navigation Tips
- i3-extras - Collection of scripts and patches
- i3ipc-glib - A library for i3 extensions
- j4tools - non-official tools designed to work with i3

Arch Linux Forums

- The i3 thread - A general discussion about i3
- i3 desktop screenshots and config sharing

Screencasts

- Containers and the tree data structure
- i3 window manager v4.1 screencast

Categories:

- Tiling WMs
- Dynamic WMs