i3 User’s Guide
===============
Michael Stapelberg <michael@i3wm.org>
-March 2013
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/
== 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):
+keybindings (click to see the full-size image):
*Keys to use with $mod (Alt):*
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.
+key (+Mod4+) being a popular alternative that largely prevents conflicts with
+application-defined shortcuts.
=== Opening terminals and moving around
=== The tree consists of Containers
-The building blocks of our tree are so called +Containers+. A +Container+ can
+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
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)
+---------------------
+
=== Comments
It is possible and recommended to use comments in your configuration file to
can configure mouse bindings in a similar way to key bindings.
*Syntax*:
--------------------------------------------------------------------------------
-bindsym [--release] [--border] [--whole-window] [<Modifiers>+]button<n> command
--------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------------------
+bindsym [--release] [--border] [--whole-window] [--exclude-titlebar] [<Modifiers>+]button<n> command
+----------------------------------------------------------------------------------------------------
By default, the binding will only run when you click on the titlebar of the
window. If the +--release+ flag is given, it will run when the mouse button
of the window is clicked, with the exception of the border. To have a bind run
when the border is clicked, specify the +--border+ flag.
+If the +--exclude-titlebar+ flag is given, the titlebar will not be considered
+for the keybinding.
+
*Examples*:
--------------------------------
# The middle button over a titlebar kills the window
=== The floating modifier
To move floating windows with your mouse, you can either grab their titlebar
-or configure the so called floating modifier which you can then press and
+or configure the so-called floating modifier which you can then press and
click anywhere in the window itself to move it. The most common setup is to
use the same key you use for managing windows (Mod1 for example). Then
you can press Mod1, click into a window using your left mouse button, and drag
workspace_layout tabbed
---------------------
-=== Border style for new windows
+=== Default border style for new windows
This option determines which border style new windows will have. The default is
-+normal+. Note that new_float applies only to windows which are starting out as
++normal+. Note that default_floating_border applies only to windows which are starting out as
floating windows, e.g., dialog windows, but not windows that are floated later on.
*Syntax*:
---------------------------------------------
-new_window normal|none|pixel
-
new_window normal|pixel <px>
-new_float normal|none|pixel
-
new_float normal|pixel <px>
+default_border normal|none|pixel
+
default_border normal|pixel <px>
+default_floating_border normal|none|pixel
+
default_floating_border normal|pixel <px>
---------------------------------------------
+Please note that +new_window+ and +new_float+ have been deprecated in favor of the above options
+and will be removed in a future release. We strongly recommend using the new options instead.
+
*Example*:
---------------------
-new_window pixel
+default_border pixel
---------------------
The "normal" and "pixel" border styles support an optional border width in
*Example*:
---------------------
-# The same as new_window none
-new_window pixel 0
+# The same as default_border none
+default_border pixel 0
# A 3 px border
-new_window pixel 3
+default_border pixel 3
---------------------
window (mapping means actually displaying it on the screen), you’d need to have
to match on 'Firefox' in this case.
+You can also assign a window to show up on a specific output. You can use RandR
+names such as +VGA1+ or names relative to the output with the currently focused
+workspace such as +left+ and +down+.
+
Assignments are processed by i3 in the order in which they appear in the config
file. The first one which matches the window wins and later assignments are not
considered.
*Syntax*:
------------------------------------------------------------
-assign <criteria> [→] [workspace] <workspace>
+assign <criteria> [→] [workspace] [number] <workspace>
+assign <criteria> [→] output left|right|up|down|primary|<output>
------------------------------------------------------------
*Examples*:
# Assignment to a named workspace
assign [class="^URxvt$"] → work
+# Assign to the workspace with number 2, regardless of name
+assign [class="^URxvt$"] → number 2
+
+# You can also specify a number + name. If the workspace with number 2 exists, assign will skip the text part.
+assign [class="^URxvt$"] → number "2: work"
+
# Start urxvt -name irssi
assign [class="^URxvt$" instance="^irssi$"] → 3
+
+# Assign urxvt to the output right of the current one
+assign [class="^URxvt$"] → output right
+
+# Assign urxvt to the primary output
+assign [class="^URxvt$"] → output primary
----------------------
-Note that the arrow is not required, it just looks good :-). If you decide to
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
+
+Also, the arrow is not required, it just looks good :-). If you decide to
use it, it has to be a UTF-8 encoded arrow, not `->` or something like that.
To get the class and instance, you can use +xprop+. After clicking on the
second part is the class ("URxvt" in this example).
Should you have any problems with assignments, make sure to check the i3
-logfile first (see http://i3wm.org/docs/debugging.html). It includes more
+logfile first (see https://i3wm.org/docs/debugging.html). It includes more
details about the matching process and the window’s actual class, instance and
title when starting up.
laptop, you might have VGA1 and LVDS1 as output names. You can see the
available outputs by running +xrandr --current+.
+If your X server supports RandR 1.5 or newer, i3 will use RandR monitor objects
+instead of output objects. Run +xrandr --listmonitors+ to see a list. Usually,
+a monitor object contains exactly one output, and has the same name as the
+output; but should that not be the case, you may specify the name of either the
+monitor or the output in i3's configuration. For example, the Dell UP2414Q uses
+two scalers internally, so its output names might be “DP1” and “DP2”, but the
+monitor name is “Dell UP2414Q”.
+
+(Note that even if you specify the name of an output which doesn't span the
+entire monitor, i3 will still use the entire area of the containing monitor
+rather than that of just the output's.)
+
If you use named workspaces, they must be quoted:
*Examples*:
=== Focus wrapping
-When being in a tabbed or stacked container, the first container will be
-focused when you use +focus down+ on the last container -- the focus wraps. If
-however there is another stacked/tabbed container in that direction, focus will
-be set on that container. This is the default behavior so you can navigate to
-all your windows without having to use +focus parent+.
+By default, when in a container with several windows or child containers, the
+opposite window will be focused when trying to move the focus over the edge of
+a container (and there are no other containers in that direction) -- the focus
+wraps.
+
+If desired, you can disable this behavior by setting the +focus_wrapping+
+configuration directive to the value +no+.
+
+When enabled, focus wrapping does not occur by default if there is another
+window or container in the specified direction, and focus will instead be set
+on that window or container. This is the default behavior so you can navigate
+to all your windows without having to use +focus parent+.
If you want the focus to *always* wrap and you are aware of using +focus
-parent+ to switch to different containers, you can use the
-+force_focus_wrapping+ configuration directive. After enabling it, the focus
-will always wrap.
+parent+ to switch to different containers, you can instead set +focus_wrapping+
+to the value +force+.
*Syntax*:
---------------------------
-force_focus_wrapping yes|no
----------------------------
+focus_wrapping yes|no|force
-*Example*:
-------------------------
+# Legacy syntax, equivalent to "focus_wrapping force"
force_focus_wrapping yes
-------------------------
+---------------------------
+
+*Examples*:
+-----------------
+# Disable focus wrapping
+focus_wrapping no
+
+# Force focus wrapping
+focus_wrapping force
+-----------------
=== Forcing Xinerama
-As explained in-depth in <http://i3wm.org/docs/multi-monitor.html>, some X11
+As explained in-depth in <https://i3wm.org/docs/multi-monitor.html>, some X11
video drivers (especially the nVidia binary driver) only provide support for
Xinerama instead of RandR. In such a situation, i3 must be told to use the
inferior Xinerama API explicitly and therefore don’t provide support for
*Syntax*:
----------------------------
-bindsym button<n> <command>
+bindsym [--release] button<n> <command>
----------------------------
*Example*:
bar {
# disable clicking on workspace buttons
bindsym button1 nop
+ # Take a screenshot by right clicking on the bar
+ bindsym --release button3 exec --no-startup-id import /tmp/latest-screenshot.png
# execute custom script when scrolling downwards
bindsym button5 exec ~/.i3/scripts/custom_wheel_down
}
*Syntax*:
---------------
-output <output>
+output primary|<output>
---------------
*Example*:
statusline #ffffff
}
}
+
+# show bar on the primary monitor and on HDMI2
+bar {
+ output primary
+ output HDMI2
+ status_command i3status
+}
+
-------------------------------
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
=== Tray output
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.
+splitv to splith or vice-versa. You can also define a custom sequence of layouts
+to cycle through with +layout toggle+, see <<manipulating_layout>>.
*Syntax*:
--------------------------------
or +layout splith+ to change the current container layout to splith/splitv,
stacking, tabbed layout, splitv or splith, respectively.
+Specify up to four layouts after +layout toggle+ to cycle through them. Every
+time the command is executed, the layout specified after the currently active
+one will be applied. If the currently active layout is not in the list, the
+first layout in the list will be activated.
+
To make the current window (!) fullscreen, use +fullscreen enable+ (or
+fullscreen enable global+ for the global mode), to leave either fullscreen
mode use +fullscreen disable+, and to toggle between these two states use
--------------------------------------------
layout default|tabbed|stacking|splitv|splith
layout toggle [split|all]
+layout toggle [split|tabbed|stacking|splitv|splith] [split|tabbed|stacking|splitv|splith]…
--------------------------------------------
*Examples*:
# Toggle between stacking/tabbed/splith/splitv:
bindsym $mod+x layout toggle all
+# Toggle between stacking/tabbed/splith:
+bindsym $mod+x layout toggle stacking tabbed splith
+
+# Toggle between splitv/tabbed
+bindsym $mod+x layout toggle splitv tabbed
+
+# Toggle between last split layout/tabbed/stacking
+bindsym $mod+x layout toggle split tabbed stacking
+
# Toggle fullscreen
bindsym $mod+f fullscreen toggle
To change focus, you can use the +focus+ command. The following options are
available:
+<criteria>::
+ Sets focus to the container that matches the specified criteria.
+ See <<command_criteria>>.
left|right|up|down::
Sets focus to the nearest container in the given direction.
parent::
*Syntax*:
----------------------------------------------
+<criteria> focus
focus left|right|down|up
focus parent|child|floating|tiling|mode_toggle
-focus output left|right|up|down|<output>
+focus output left|right|up|down|primary|<output>
----------------------------------------------
*Examples*:
-------------------------------------------------
+# Focus firefox
+bindsym $mod+F1 [class="Firefox"] focus
+
# Focus container on the left, bottom, top, right
bindsym $mod+j focus left
bindsym $mod+k focus down
# Focus the big output
bindsym $mod+x focus output HDMI-2
+
+# Focus the primary output
+bindsym $mod+x focus output primary
-------------------------------------------------
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
+
=== Moving containers
Use the +move+ command to move a container.
bindsym $mod+m move position mouse
-------------------------------------------------------
+=== Swapping containers
+
+Two containers can be swapped (i.e., move to each other's position) by using
+the +swap+ command. They will assume the position and geometry of the container
+they are swapped with.
+
+The first container to participate in the swapping can be selected through the
+normal command criteria process with the focused window being the usual
+fallback if no criteria are specified. The second container can be selected
+using one of the following methods:
+
++id+:: The X11 window ID of a client window.
++con_id+:: The i3 container ID of a container.
++mark+:: A container with the specified mark, see <<vim_like_marks>>.
+
+Note that swapping does not work with all containers. Most notably, swapping
+floating containers or containers that have a parent-child relationship to one
+another does not work.
+
+*Syntax*:
+----------------------------------------
+swap container with id|con_id|mark <arg>
+----------------------------------------
+
+*Examples*:
+-----------------------------------------------------------------
+# Swaps the focused container with the container marked »swapee«.
+swap container with mark swapee
+
+# Swaps container marked »A« and »B«
+[con_mark="^A$"] swap container with mark B
+-----------------------------------------------------------------
+
=== Sticky floating windows
If you want a window to stick to the glass, i.e., have it stay on screen even
*Syntax*:
------------------------------------------------------------
-move container to output left|right|down|up|current|<output>
-move workspace to output left|right|down|up|current|<output>
+move container to output left|right|down|up|current|primary|<output>
+move workspace to output left|right|down|up|current|primary|<output>
------------------------------------------------------------
*Examples*:
# Put this window on the presentation output.
bindsym $mod+x move container to output VGA1
+
+# Put this window on the primary output.
+bindsym $mod+x move container to output primary
--------------------------------------------------------
+Note that you might not have a primary output configured yet. To do so, run:
+-------------------------
+xrandr --output <output> --primary
+-------------------------
+
=== Moving containers/windows to marks
To move a container to another container with a specific mark (see <<vim_like_marks>>),
*Syntax*:
-------------------------------------------------------
resize grow|shrink <direction> [<px> px [or <ppt> ppt]]
-resize set <width> [px] <height> [px]
+resize set <width> [px | ppt] <height> [px | ppt]
-------------------------------------------------------
Direction can either be one of +up+, +down+, +left+ or +right+. Or you can be
how many pixels a *floating container* should be grown or shrunk (the default
is 10 pixels). The ppt argument means percentage points and specifies by how
many percentage points a *tiling container* should be grown or shrunk (the
-default is 10 percentage points). Note that +resize set+ will only work for
-floating containers.
+default is 10 percentage points).
+
+Notes about +resize set+: a value of 0 for <width> or <height> means "do
+not resize in this direction", and resizing a tiling container by +px+ is not
+implemented.
It is recommended to define bindings for resizing in a dedicated binding mode.
See <<binding_modes>> and the example in the i3
*Examples*:
---------------------------------------
# Read 1 character and mark the current window with this character
-bindsym $mod+m exec i3-input -p 'mark ' -l 1 -P 'Mark: '
+bindsym $mod+m exec i3-input -F 'mark %s' -l 1 -P 'Mark: '
# Read 1 character and go to the window with the character
-bindsym $mod+g exec i3-input -p 'goto ' -l 1 -P 'Goto: '
+bindsym $mod+g exec i3-input -F '[con_mark="%s"] focus' -l 1 -P 'Goto: '
---------------------------------------
Alternatively, if you do not want to mess with +i3-input+, you could create
[[shmlog]]
=== Enabling shared memory logging
-As described in http://i3wm.org/docs/debugging.html, i3 can log to a shared
+As described in https://i3wm.org/docs/debugging.html, i3 can log to a shared
memory buffer, which you can dump using +i3-dump-log+. The +shmlog+ command
allows you to enable or disable the shared memory logging at runtime.
projects / i3 / i3 / blobdiff