I3 User Guide

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 46

Download
Open PDF In Browser	View PDF

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

Docs

Screens

FAQ

Contact

Bugs

i3 User’s Guide
Michael Stapelberg

March 2013

Table of Contents
1. Default keybindings
2. Using i3
2.1. Opening terminals and moving around
2.2. Changing the container layout
2.3. Toggling fullscreen mode for a window
2.4. Opening other applications
2.5. Closing windows
2.6. Using workspaces
2.7. Moving windows to workspaces
2.8. Resizing
2.9. Restarting i3 inplace
2.10. Exiting i3
2.11. Floating

3. Tree
3.1. The tree consists of Containers
3.2. Orientation and Split Containers
3.3. Focus parent
3.4. Implicit containers

4. Configuring i3
4.1. Comments
4.2. Fonts
4.3. Keyboard bindings
4.4. Mouse bindings
4.5. Binding modes
4.6. The floating modifier
4.7. Constraining floating window size
4.8. Orientation for new workspaces
4.9. Layout mode for new containers
4.10. Border style for new windows
4.11. Hiding borders adjacent to the screen edges
4.12. Arbitrary commands for specific windows (for_window)
4.13. Don’t focus window upon opening
4.14. Variables
4.15. X resources
4.16. Automatically putting clients on specific workspaces
4.17. Automatically starting applications on i3 startup
4.18. Automatically putting workspaces on specific screens
4.19. Changing colors
4.20. Interprocess communication
4.21. Focus follows mouse

1 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

4.22. Mouse warping
4.23. Popups during fullscreen mode
4.24. Focus wrapping
4.25. Forcing Xinerama
4.26. Automatic back-and-forth when switching to the current workspace
4.27. Delaying urgency hint reset on workspace change
4.28. Focus on window activation
4.29. Drawing marks on window decoration
4.30. Line continuation

5. Configuring i3bar
5.1. i3bar command
5.2. Statusline command
5.3. Display mode
5.4. Mouse button commands
5.5. Bar ID
5.6. Position
5.7. Output(s)
5.8. Tray output
5.9. Tray padding
5.10. Font
5.11. Custom separator symbol
5.12. Workspace buttons
5.13. Strip workspace numbers
5.14. Binding Mode indicator
5.15. Colors

6. List of commands
6.1. Executing applications (exec)
6.2. Splitting containers
6.3. Manipulating layout
6.4. Focusing containers
6.5. Moving containers
6.6. Swapping containers
6.7. Sticky floating windows
6.8. Changing (named) workspaces/moving to workspaces
6.9. Moving workspaces to a different screen
6.10. Moving containers/workspaces to RandR outputs

7. move window|container to mark 
7.1. Resizing containers/windows
7.2. Jumping to specific windows
7.3. VIM-like marks (mark/goto)
7.4. Window title format
7.5. Changing border style
7.6. Enabling shared memory logging
7.7. Enabling debug logging
7.8. Reloading/Restarting/Exiting
7.9. Scratchpad
7.10. Nop
7.11. i3bar control

8. Multiple monitors
8.1. Configuring your monitors
8.2. Interesting configuration for multi-monitor environments

9. i3 and the rest of your software world
9.1. Displaying a status line
9.2. Giving presentations (multi-monitor)

2 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

This document contains all the information you need to configure and use the i3 window manager. If it does not, please
check https://www.reddit.com/r/i3wm/ first, then contact us on IRC (preferred) or post your question(s) on the mailing
list.

1. Default keybindings
For the "too long; didn’t read" people, here is an overview of the default keybindings (click to see the full size image):
Keys to use with $mod (Alt):

Keys to use with Shift+$mod:

The red keys are the modifiers you need to press (by default), the blue keys are your homerow.
Note that when starting i3 without a config file, i3-config-wizard will offer you to create a config file in which the key
positions (!) match what you see in the image above, regardless of the keyboard layout you are using. If you prefer to use
a config file where the key letters match what you are seeing above, just decline i3-config-wizard’s offer and base your
config on /etc/i3/config.

2. Using i3
Throughout this guide, the keyword $mod will be used to refer to the configured modifier. This is the Alt key (Mod1) by
default, with the Windows key (Mod4) being a popular alternative.

2.1. Opening terminals and moving around
One very basic operation is opening a new terminal. By default, the keybinding for this is $mod+Enter, that is Alt+Enter
(Mod1+Enter) in the default configuration. By pressing $mod+Enter, a new terminal will be opened. It will fill the whole
space available on your screen.

3 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

If you now open another terminal, i3 will place it next to the current one, splitting the screen size in half. Depending on
your monitor, i3 will put the created window beside the existing window (on wide displays) or below the existing window
(rotated displays).

To move the focus between the two terminals, you can use the direction keys which you may know from the editor vi.
However, in i3, your homerow is used for these keys (in vi, the keys are shifted to the left by one for compatibility with
most keyboard layouts). Therefore, $mod+j is left, $mod+k is down, $mod+l is up and $mod+; is right. So, to switch
between the terminals, use $mod+k or $mod+l. Of course, you can also use the arrow keys.
At the moment, your workspace is split (it contains two terminals) in a specific direction (horizontal by default). Every
window can be split horizontally or vertically again, just like the workspace. The terminology is "window" for a container
that actually contains an X11 window (like a terminal or browser) and "split container" for containers that consist of one
or more windows.
TODO: picture of the tree
To split a window vertically, press $mod+v before you create the new window. To split it horizontally, press $mod+h.

2.2. Changing the container layout
A split container can have one of the following layouts:
splith/splitv
Windows are sized so that every window gets an equal amount of space in the container. splith distributes the
windows horizontally (windows are right next to each other), splitv distributes them vertically (windows are on top
of each other).
stacking
Only the focused window in the container is displayed. You get a list of windows at the top of the container.
tabbed
The same principle as stacking, but the list of windows at the top is only a single line which is vertically split.
To switch modes, press $mod+e for splith/splitv (it toggles), $mod+s for stacking and $mod+w for tabbed.

4 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

2.3. Toggling fullscreen mode for a window
To display a window in fullscreen mode or to go out of fullscreen mode again, press $mod+f.
There is also a global fullscreen mode in i3 in which the client will span all available outputs (the command is
fullscreen toggle global).

2.4. Opening other applications
Aside from opening applications from a terminal, you can also use the handy dmenu which is opened by pressing $mod+d
by default. Just type the name (or a part of it) of the application which you want to open. The corresponding application
has to be in your $PATH for this to work.
Additionally, if you have applications you open very frequently, you can create a keybinding for starting the application
directly. See the section [configuring] for details.

2.5. Closing windows
If an application does not provide a mechanism for closing (most applications provide a menu, the escape key or a
shortcut like Control+w to close), you can press $mod+Shift+q to kill a window. For applications which support the
WM_DELETE protocol, this will correctly close the application (saving any modifications or doing other cleanup). If the
application doesn’t support the WM_DELETE protocol your X server will kill the window and the behaviour depends on the
application.

2.6. Using workspaces
Workspaces are an easy way to group a set of windows. By default, you are on the first workspace, as the bar on the
bottom left indicates. To switch to another workspace, press $mod+num where num is the number of the workspace you
want to use. If the workspace does not exist yet, it will be created.
A common paradigm is to put the web browser on one workspace, communication applications (mutt, irssi, …) on
another one, and the ones with which you work, on the third one. Of course, there is no need to follow this approach.
If you have multiple screens, a workspace will be created on each screen at startup. If you open a new workspace, it will
be bound to the screen you created it on. When you switch to a workspace on another screen, i3 will set focus to that
screen.

2.7. Moving windows to workspaces
To move a window to another workspace, simply press $mod+Shift+num where num is (like when switching workspaces)
the number of the target workspace. Similarly to switching workspaces, the target workspace will be created if it does not
yet exist.

2.8. Resizing
The easiest way to resize a container is by using the mouse: Grab the border and move it to the wanted size.
You can also use [binding_modes] to define a mode for resizing via the keyboard. To see an example for this, look at the
default config provided by i3.

5 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

2.9. Restarting i3 inplace
To restart i3 in place (and thus get into a clean state if there is a bug, or to upgrade to a newer version of i3) you can use
$mod+Shift+r.

2.10. Exiting i3
To cleanly exit i3 without killing your X server, you can use $mod+Shift+e. By default, a dialog will ask you to confirm if
you really want to quit.

2.11. Floating
Floating mode is the opposite of tiling mode. The position and size of a window are not managed automatically by i3, but
manually by you. Using this mode violates the tiling paradigm but can be useful for some corner cases like "Save as"
dialog windows, or toolbar windows (GIMP or similar). Those windows usually set the appropriate hint and are opened in
floating mode by default.
You can toggle floating mode for a window by pressing $mod+Shift+Space. By dragging the window’s titlebar with your
mouse you can move the window around. By grabbing the borders and moving them you can resize the window. You can
also do that by using the [floating_modifier]. Another way to resize floating windows using the mouse is to right-click on
the titlebar and drag.
For resizing floating windows with your keyboard, see the resizing binding mode provided by the i3 default config.
Floating windows are always on top of tiling windows.

3. Tree
i3 stores all information about the X11 outputs, workspaces and layout of the windows on them in a tree. The root node is
the X11 root window, followed by the X11 outputs, then dock areas and a content container, then workspaces and finally
the windows themselves. In previous versions of i3 we had multiple lists (of outputs, workspaces) and a table for each
workspace. That approach turned out to be complicated to use (snapping), understand and implement.

3.1. The tree consists of Containers
The building blocks of our tree are so called Containers. A Container can host a window (meaning an X11 window,
one that you can actually see and use, like a browser). Alternatively, it could contain one or more Containers. A simple
example is the workspace: When you start i3 with a single monitor, a single workspace and you open two terminal
windows, you will end up with a tree like this:

Figure 1. Two terminals on standard workspace

3.2. Orientation and Split Containers
It is only natural to use so-called Split Containers in order to build a layout when using a tree as data structure. In i3,
every Container has an orientation (horizontal, vertical or unspecified) and the orientation depends on the layout the
container is in (vertical for splitv and stacking, horizontal for splith and tabbed). So, in our example with the workspace,

6 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

the default layout of the workspace Container is splith (most monitors are widescreen nowadays). If you change the
layout to splitv ($mod+v in the default config) and then open two terminals, i3 will configure your windows like this:

Figure 2. Vertical Workspace Orientation
An interesting new feature of i3 since version 4 is the ability to split anything: Let’s assume you have two terminals on a
workspace (with splith layout, that is horizontal orientation), focus is on the right terminal. Now you want to open another
terminal window below the current one. If you would just open a new terminal window, it would show up to the right due
to the splith layout. Instead, press $mod+v to split the container with the splitv layout (to open a Horizontal Split
Container, use $mod+h). Now you can open a new terminal and it will open below the current one:

Figure 3. Vertical Split Container

You probably guessed it already: There is no limit on how deep your hierarchy of splits can be.

3.3. Focus parent
Let’s stay with our example from above. We have a terminal on the left and two vertically split terminals on the right,
focus is on the bottom right one. When you open a new terminal, it will open below the current one.
So, how can you open a new terminal window to the right of the current one? The solution is to use focus parent,
which will focus the Parent Container of the current Container. In this case, you would focus the Vertical Split
Container which is inside the horizontally oriented workspace. Thus, now new windows will be opened to the right of
the Vertical Split Container:

Figure 4. Focus parent, then open new terminal

7 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

3.4. Implicit containers
In some cases, i3 needs to implicitly create a container to fulfill your command.
One example is the following scenario: You start i3 with a single monitor and a single workspace on which you open three
terminal windows. All these terminal windows are directly attached to one node inside i3’s layout tree, the workspace
node. By default, the workspace node’s orientation is horizontal.
Now you move one of these terminals down ($mod+Shift+k by default). The workspace node’s orientation will be
changed to vertical. The terminal window you moved down is directly attached to the workspace and appears on the
bottom of the screen. A new (horizontal) container was created to accommodate the other two terminal windows. You will
notice this when switching to tabbed mode (for example). You would end up having one tab with a representation of the
split container (e.g., "H[urxvt firefox]") and the other one being the terminal window you moved down.

4. Configuring i3
This is where the real fun begins ;-). Most things are very dependent on your ideal working environment so we can’t make
reasonable defaults for them.
While not using a programming language for the configuration, i3 stays quite flexible in regards to the things you usually
want your window manager to do.
For example, you can configure bindings to jump to specific windows, you can set specific applications to start on specific
workspaces, you can automatically start applications, you can change the colors of i3, and you can bind your keys to do
useful things.
To change the configuration of i3, copy /etc/i3/config to ~/.i3/config (or ~/.config/i3/config if you like the
XDG directory scheme) and edit it with a text editor.
On first start (and on all following starts, unless you have a configuration file), i3 will offer you to create a configuration
file. You can tell the wizard to use either Alt (Mod1) or Windows (Mod4) as modifier in the config file. Also, the created
config file will use the key symbols of your current keyboard layout. To start the wizard, use the command i3-configwizard. Please note that you must not have ~/.i3/config, otherwise the wizard will exit.
Since i3 4.0, a new configuration format is used. i3 will try to automatically detect the format version of a config file based
on a few different keywords, but if you want to make sure that your config is read with the new format, include the
following line in your config file:
# i3 config file (v4)

4.1. Comments
It is possible and recommended to use comments in your configuration file to properly document your setup for later
reference. Comments are started with a # and can only be used at the beginning of a line:
Examples:
# This is a comment

4.2. Fonts
i3 has support for both X core fonts and FreeType fonts (through Pango) to render window titles.
To generate an X core font description, you can use xfontsel(1). To see special characters (Unicode), you need to use a
font which supports the ISO-10646 encoding.
A FreeType font description is composed by a font family, a style, a weight, a variant, a stretch and a size. FreeType fonts
support right-to-left rendering and contain often more Unicode glyphs than X core fonts.

8 of 46

12/25/17, 2:22 AM

i3: i3 User’s Guide

https://i3wm.org/docs/userguide.html

If i3 cannot open the configured font, it will output an error in the logfile and fall back to a working font.
Syntax:
font 
font pango: [