March 2013
This document contains all the information you need to configure and use the i3
-window manager. If it does not, please check http://faq.i3wm.org/ first, then
-contact us on IRC (preferred) or post your question(s) on the mailing list.
+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.
== Default keybindings
== 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.
+configured modifier. This is the Alt key (+Mod1+) by default, with the Windows
+key (+Mod4+) being a popular alternative.
=== 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 in the default configuration. By
-pressing $mod+Enter, a new terminal will be opened. It will fill the whole
-space available on your screen.
+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.
image:single_terminal.png[Single terminal]
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.
+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
=== 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
+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
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
+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-config-wizard+.
Please note that you must not have +~/.i3/config+, otherwise the wizard will
---------------------
-=== Hiding vertical borders
+[[_hiding_vertical_borders]]
+=== Hiding borders adjacent to the screen edges
-You can hide vertical borders adjacent to the screen edges using
+You can hide container borders adjacent to the screen edges using
+hide_edge_borders+. This is useful if you are using scrollbars, or do not want
-to waste even two pixels in displayspace. Default is none.
+to waste even two pixels in displayspace. The "smart" setting hides borders on
+workspaces with only one window visible, but keeps them on workspaces with
+multiple windows visible. Default is none.
*Syntax*:
-----------------------------------------------
-hide_edge_borders none|vertical|horizontal|both
+hide_edge_borders none|vertical|horizontal|both|smart
-----------------------------------------------
*Example*:
you should create a little script which generates a configuration file and run
it before starting i3 (for example in your +~/.xsession+ file).
+Also see <<xresources>> to learn how to create variables based on resources
+loaded from the X resource database.
+
+[[xresources]]
+=== X resources
+
+<<variables>> can also be created using a value configured in the X resource
+database. This is useful, for example, to avoid configuring color values within
+the i3 configuration. Instead, the values can be configured, once, in the X
+resource database to achieve an easily maintainable, consistent color theme
+across many X applications.
+
+Defining a resource will load this resource from the resource database and
+assign its value to the specified variable. A fallback must be specified in
+case the resource cannot be loaded from the database.
+
+*Syntax*:
+----------------------------------------------------
+set_from_resource $<name> <resource_name> <fallback>
+----------------------------------------------------
+
+*Example*:
+----------------------------------------------------------------------------
+# The ~/.Xresources should contain a line such as
+# *color0: #121212
+# and must be loaded properly, e.g., by using
+# xrdb ~/.Xresources
+# This value is picked up on by other applications (e.g., the URxvt terminal
+# emulator) and can be used in i3 like this:
+set_from_resource $black i3wm.color0 #000000
+----------------------------------------------------------------------------
+
[[assign_workspace]]
=== Automatically putting clients on specific workspaces
See <<command_chaining>> for details on the special meaning of +;+ (semicolon)
and +,+ (comma): they chain commands together in i3, so you need to use quoted
-strings if they appear in your command.
+strings (as shown in <<exec_quoting>>) if they appear in your command.
*Syntax*:
---------------------------------------
You can change all colors which i3 uses to draw the window decorations.
*Syntax*:
-------------------------------------------------------
-<colorclass> <border> <background> <text> <indicator>
-------------------------------------------------------
+--------------------------------------------------------------------
+<colorclass> <border> <background> <text> <indicator> <child_border>
+--------------------------------------------------------------------
Where colorclass can be one of:
Colors are in HTML hex format (#rrggbb), see the following example:
*Examples (default colors)*:
----------------------------------------------------------
-# class border backgr. text indicator
-client.focused #4c7899 #285577 #ffffff #2e9ef4
-client.focused_inactive #333333 #5f676a #ffffff #484e50
-client.unfocused #333333 #222222 #888888 #292d2e
-client.urgent #2f343a #900000 #ffffff #900000
-client.placeholder #000000 #0c0c0c #ffffff #000000
+----------------------------------------------------------------------
+# class border backgr. text indicator child_border
+client.focused #4c7899 #285577 #ffffff #2e9ef4 #285577
+client.focused_inactive #333333 #5f676a #ffffff #484e50 #5f676a
+client.unfocused #333333 #222222 #888888 #292d2e #222222
+client.urgent #2f343a #900000 #ffffff #900000 #900000
+client.placeholder #000000 #0c0c0c #ffffff #000000 #0c0c0c
client.background #ffffff
----------------------------------------------------------
+----------------------------------------------------------------------
Note that for the window decorations, the color around the child window is the
-background color, and the border color is only the two thin lines at the top of
-the window.
+"child_border", and "border" color is only the two thin lines around the
+titlebar.
The indicator color is used for indicating where a new window will be opened.
For horizontal split containers, the right border will be painted in indicator
Config files support line continuation, meaning when you end a line in a
backslash character (`\`), the line-break will be ignored by the parser. This
feature can be used to create more readable configuration files.
+Commented lines are not continued.
*Examples*:
-------------------
bindsym Mod1+f \
fullscreen toggle
+
+# this line is not continued \
+bindsym Mod1+F fullscreen toggle
-------------------
== Configuring i3bar
-------------------------
mode dock|hide|invisible
hidden_state hide|show
-modifier <Modifier>
+modifier <Modifier>|none
------------------------
*Example*:
}
----------------
-Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+).
+Available modifiers are Mod1-Mod5, Shift, Control (see +xmodmap(1)+). You can
+also use "none" if you don't want any modifier to trigger this behavior.
=== Mouse button commands
You can configure on which output (monitor) the icons should be displayed or
you can turn off the functionality entirely.
+You can use multiple +tray_output+ directives in your config to specify a list
+of outputs on which you want the tray to appear. The first available output in
+that list as defined by the order of the directives will be used for the tray
+output.
+
*Syntax*:
---------------------------------
tray_output none|primary|<output>
Text color to be used for the statusline.
separator::
Text color to be used for the separator.
+focused_background::
+ Background color of the bar on the currently focused monitor output. If
+ not used, the color will be taken from +background+.
+focused_statusline::
+ Text color to be used for the statusline on the currently focused
+ monitor output. If not used, the color will be taken from +statusline+.
+focused_separator::
+ Text color to be used for the separator on the currently focused
+ monitor output. If not used, the color will be taken from +separator+.
focused_workspace::
Border, background and text color for a workspace button when the workspace
has focus.
# enable floating mode and move container to workspace 4
for_window [class="^evil-app$"] floating enable, move container to workspace 4
+
+# move all floating windows to the scratchpad
+bindsym $mod+x [floating] move scratchpad
------------------------------------
The criteria which are currently implemented are:
window_type::
Compare the window type (_NET_WM_WINDOW_TYPE). Possible values are
+normal+, +dialog+, +utility+, +toolbar+, +splash+, +menu+, +dropdown_menu+,
- +popup_menu+ and +tooltip+.
+ +popup_menu+, +tooltip+ and +notification+.
id::
Compares the X11 window ID, which you can get via +xwininfo+ for example.
title::
the special value +\_\_focused__+ to match all windows in the currently
focused workspace.
con_mark::
- Compares the mark set for this container, see <<vim_like_marks>>.
+ Compares the marks set for this container, see <<vim_like_marks>>. A
+ match is made if any of the container's marks matches the specified
+ mark.
con_id::
Compares the i3-internal container ID, which you can get via the IPC
- interface. Handy for scripting.
+ interface. Handy for scripting. Use the special value +\_\_focused__+
+ to match only the currently focused window.
+floating::
+ Only matches floating windows. This criterion requires no value.
+tiling::
+ Only matches tiling windows. This criterion requires no value.
The criteria +class+, +instance+, +role+, +title+, +workspace+ and +mark+ are
actually regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for
See <<command_chaining>> for details on the special meaning of +;+ (semicolon)
and +,+ (comma): they chain commands together in i3, so you need to use quoted
-strings if they appear in your command.
+strings (as shown in <<exec_quoting>>) if they appear in your command.
*Syntax*:
--------------------------------
and Qt using applications seem to be, though), you will end up with a watch
cursor for 60 seconds.
+[[exec_quoting]]
+If the command to be executed contains a +;+ (semicolon) and/or a +,+ (comma),
+the entire command must be quoted. For example, to have a keybinding for the
+shell command +notify-send Hello, i3+, you would add an entry to your
+configuration file like this:
+
+*Example*:
+------------------------------
+# Execute a command with a comma in it
+bindsym $mod+p exec "notify-send Hello, i3"
+------------------------------
+
+If however a command with a comma and/or semicolon itself requires quotes, you
+must escape the internal quotation marks with double backslashes, like this:
+
+*Example*:
+------------------------------
+# Execute a command with a comma, semicolon and internal quotes
+bindsym $mod+p exec "notify-send \\"Hello, i3; from $USER\\""
+------------------------------
+
=== Splitting containers
The split command makes the current window a split container. Split containers
If you apply this command to a split container with the same orientation,
nothing will happen. If you use a different orientation, the split container’s
-orientation will be changed (if it does not have more than one window). Use
-+layout toggle split+ to change the layout of any split container from splitv
-to splith or vice-versa.
+orientation will be changed (if it does not have more than one window).
+The +toggle+ option will toggle the orientation of the split container if it
+contains a single window. Otherwise it makes the current window a split
+container with opposite orientation compared to the parent container.
+Use +layout toggle split+ to change the layout of any split container from
+splitv to splith or vice-versa.
*Syntax*:
--------------------------
-split vertical|horizontal
--------------------------
+--------------------------------
+split vertical|horizontal|toggle
+--------------------------------
*Example*:
-------------------------------
+-------------------------------
bindsym $mod+v split vertical
bindsym $mod+h split horizontal
-------------------------------
+bindsym $mod+t split toggle
+-------------------------------
=== Manipulating layout
=== Changing (named) workspaces/moving to workspaces
To change to a specific workspace, use the +workspace+ command, followed by the
-number or name of the workspace. To move containers to specific workspaces, use
-+move container to workspace+.
+number or name of the workspace. Pass the optional flag
++--no-auto-back-and-forth+ to disable <<back_and_forth>> for this specific call
+only.
+
+To move containers to specific workspaces, use +move container to workspace+.
You can also switch to the next and previous workspace with the commands
+workspace next+ and +workspace prev+, which is handy, for example, if you have
workspace using +move container to workspace back_and_forth+.
*Syntax*:
------------------------------------
+--------------------------------------------------------------------------------
workspace next|prev|next_on_output|prev_on_output
workspace back_and_forth
-workspace <name>
-workspace number <name>
+workspace [--no-auto-back-and-forth] <name>
+workspace [--no-auto-back-and-forth] number <name>
-move [window|container] [to] workspace <name>
-move [window|container] [to] workspace number <name>
+move [--no-auto-back-and-forth] [window|container] [to] workspace <name>
+move [--no-auto-back-and-forth] [window|container] [to] workspace number <name>
move [window|container] [to] workspace prev|next|current
------------------------------------
+--------------------------------------------------------------------------------
*Examples*:
-------------------------
RandR output.
[[move_to_outputs]]
+[[_moving_containers_workspaces_to_randr_outputs]]
=== Moving containers/workspaces to RandR outputs
To move a container to another RandR output (addressed by names like +LVDS1+ or
can also prefix this command and display a custom prompt for the input dialog.
The additional +--toggle+ option will remove the mark if the window already has
-this mark, add it if the window has none or replace the current mark if it has
-another mark.
+this mark or add it otherwise. Note that you may need to use this in
+combination with +--add+ (see below) as any other marks will otherwise be
+removed.
+
+By default, a window can only have one mark. You can use the +--add+ flag to
+put more than one mark on a window.
Refer to <<show_marks>> if you don't want marks to be shown in the window decoration.
*Syntax*:
-------------------------------
-mark [--toggle] <identifier>
+----------------------------------------------
+mark [--add|--replace] [--toggle] <identifier>
[con_mark="identifier"] focus
unmark <identifier>
-------------------------------
+----------------------------------------------
*Example (in a terminal)*:
-------------------------------
-$ i3-msg mark irssi
-$ i3-msg '[con_mark="irssi"] focus'
-$ i3-msg unmark irssi
-------------------------------
+---------------------------------------------------------
+# marks the focused container
+mark irssi
+
+# focus the container with the mark "irssi"
+'[con_mark="irssi"] focus'
+
+# remove the mark "irssi" from whichever container has it
+unmark irssi
+
+# remove all marks on all firefox windows
+[class="(?i)firefox"] unmark
+---------------------------------------------------------
///////////////////////////////////////////////////////////////////
TODO: make i3-input replace %s
---------------------------------------
Alternatively, if you do not want to mess with +i3-input+, you could create
-seperate bindings for a specific set of labels and then only use those labels.
+separate bindings for a specific set of labels and then only use those labels.
///////////////////////////////////////////////////////////////////
[[pango_markup]]
and the following placeholders which will be replaced:
+%title+::
- The X11 window title (_NET_WM_NAME or WM_NAME as fallback).
+ For normal windows, this is the X11 window title (_NET_WM_NAME or WM_NAME
+ as fallback). When used on containers without a window (e.g., a split
+ container inside a tabbed/stacked layout), this will be the tree
+ representation of the container (e.g., "H[xterm xterm]").
+%class+::
The X11 window class (second part of WM_CLASS). This corresponds to the
+class+ criterion, see <<command_criteria>>.
There is also +border toggle+ which will toggle the different border styles.
+Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel
+may be represented by multiple physical pixels, so +pixel 1+ might not
+necessarily translate into a single pixel row wide border.
+
*Syntax*:
-----------------------------------------------
border normal|pixel [<n>]
track of which window you put where. Thus, you can use vim-like marks to
quickly switch between windows. See <<vim_like_marks>>.
4. For information on how to move existing workspaces between monitors,
- see <<_moving_containers_workspaces_to_randr_outputs>>.
+ see <<move_to_outputs>>.
== i3 and the rest of your software world