i3 User’s Guide
===============
Michael Stapelberg <michael+i3@stapelberg.de>
-July 2011
-
-*********************************************************************************
-This document is not yet finished. The tree branch is still in development. The
-information provided here should be correct, just not complete yet.
-*********************************************************************************
+August 2011
This document contains all the information you need to configure and use the i3
window manager. If it does not, please contact us on IRC (preferred) or post your
question(s) on the mailing list.
-//////////////////////////////////////////////////////////////////////////////
== Default keybindings
For the "too long; didn’t read" people, here is an overview of the default
image:keyboard-layer2.png["Keys to use with Shift+mod",width=600,link="keyboard-layer2.png"]
-As i3 uses keycodes in the default configuration, it does not matter which
-keyboard layout you actually use. The key positions are what matters (of course
-you can also use keysymbols, see <<keybindings>>).
-
The red keys are the modifiers you need to press (by default), the blue keys
are your homerow.
-//////////////////////////////////////////////////////////////////////////////
== Using i3
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
-new window right to the old window (for widescreen) or below the old window
-(rotated displays).
+created window beside the existing window (on wide displays) or below the
+existing window (rotated displays).
image:two_terminals.png[Two terminals]
-To move the focus between the two terminals, you 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.
+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
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 default, +mod+h+ for stacking and
+To switch modes, press +mod+e+ for default, +mod+s+ for stacking and
+mod+w+ for tabbed.
image:modes.png[Container modes]
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 use all
+There is also a global fullscreen mode in i3 in which the client will span all
available outputs.
=== Opening other applications
(anything wider than high) get horizontal orientation, rotated monitors
(anything higher than wide) get vertical orientation.
-With the +default_orientation+ configuration directive, you can overwrite that
+With the +default_orientation+ configuration directive, you can override that
behaviour.
*Syntax*:
new_window 1pixel
---------------------
+=== Arbitrary commands for specific windows (for_window)
+
+With the +for_window+ command, you can let i3 execute any command when it
+encounters a specific window. This can be used to set windows to floating or to
+change their border style, for example.
+
+*Syntax*:
+-----------------------------
+for_window [criteria] command
+-----------------------------
+
+*Examples*:
+------------------------------------------------
+# enable floating mode for all XTerm windows
+for_window [class="XTerm"] floating enable
+
+# Make all urxvts use a 1-pixel border:
+for_window [class="urxvt"] border 1pixel
+
+# A less useful, but rather funny example:
+# makes the window floating as soon as I change
+# directory to ~/work
+for_window [title="x200: ~/work"] floating enable
+------------------------------------------------
+
=== Variables
As you learned in the section about keyboard bindings, you will have
[[assign_workspace]]
-It is recommended that you match on window classes insetead of window titles
-whenever possible because some applications first create their window, and then
-worry about setting the correct title. Firefox with Vimperator comes to mind.
-The window starts up being named Firefox, and only when Vimperator is loaded
-does the title change. As i3 will get the title as soon as the application maps
-the window (mapping means actually displaying it on the screen), you’d need to
-have to match on 'Firefox' in this case.
+Specific windows can be matched by window class and/or window title. It is
+recommended that you match on window classes instead of window titles whenever
+possible because some applications first create their window, and then worry
+about setting the correct title. Firefox with Vimperator comes to mind. The
+window starts up being named Firefox, and only when Vimperator is loaded does
+the title change. As i3 will get the title as soon as the application maps the
+window (mapping means actually displaying it on the screen), you’d need to have
+to match on 'Firefox' in this case.
You can prefix or suffix workspaces with a `~` to specify that matching clients
should be put into floating mode. If you specify only a `~`, the client will
*Examples*:
--------------------------------
-exec i3status | dzen2 -dock
+exec i3status | i3bar -d
exec_always ~/my_script.sh
--------------------------------
=== Changing colors
-You can change all colors which i3 uses to draw the window decorations and the
-bottom bar.
+You can change all colors which i3 uses to draw the window decorations.
*Syntax*:
--------------------------------------------
A client which is not the focused one of its container.
client.urgent::
A client which has its urgency hint activated.
-bar.focused::
- The current workspace in the bottom bar.
-bar.unfocused::
- All other workspaces in the bottom bar.
-bar.urgent::
- A workspace which has at least one client with an activated urgency hint.
You can also specify the color to be used to paint the background of the client
windows. This color will be used to paint the window on top of which the client
Colors are in HTML hex format (#rrggbb), see the following example:
-*Examples*:
---------------------------------------
-# class border backgr. text
-client.focused #2F343A #900000 #FFFFFF
---------------------------------------
+*Examples (default colors)*:
+-----------------------------------------------
+# class border backgr. text
+client.focused #4c7899 #285577 #ffffff
+client.focused_inactive #333333 #5f676a #ffffff
+client.unfocused #333333 #222222 #888888
+client.urgent #2f343a #900000 #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
of i3.
You can override the default path through the environment-variable +I3SOCK+ or
-by specifying the +ipc-socket+ directive.
+by specifying the +ipc-socket+ directive. This is discouraged, though, since i3
+does the right thing by default.
*Examples*:
----------------------------
popup_during_fullscreen ignore
------------------------------
+=== 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 behaviour 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.
+
+*Syntax*:
+-----------------------------
+force_focus_wrapping <yes|no>
+-----------------------------
+
+*Example*:
+------------------------
+force_focus_wrapping yes
+------------------------
+
== List of commands
+=== Splitting containers
+
+The split command makes the current window a split container. Split containers
+can contain multiple windows. Every split container has an orientation, it is
+either split horizontally (a new window gets placed to the right of the current
+one) or vertically (a new window gets placed below the current one).
+
+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).
+
+*Syntax*:
+---------------------------
+split <vertical|horizontal>
+---------------------------
+
+*Example*:
+------------------------------
+bindsym mod+v split vertical
+bindsym mod+h split horizontal
+------------------------------
+
=== Manipulating layout
-To change the layout of the current container to stacking, use +layout
-stacking+, for default use +layout default+ and for tabbed, use +layout
-tabbed+. To make the current window (!) fullscreen, use +fullscreen+, to make
+Use +layout default+, +layout stacking+ or +layout tabbed+ to change the
+current container layout to default, stacking or tabbed layout, respectively.
+
+To make the current window (!) fullscreen, use +fullscreen+, to make
it floating (or tiling again) use +floating enable+ respectively +floating disable+
(or +floating toggle+):
bindsym mod+semicolon move right
----------------------
-=== Changing workspaces/moving containers to workspaces
+=== 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
workspace 1, 3, 4 and 9 and you want to cycle through them with a single key
combination.
+To move a container to another xrandr output such as +LVDS1+ or +VGA1+, you can
+use the +move output+ command followed by the name of the target output. You
+may also use +left+, +right+, +up+, +down+ instead of the xrandr output name to
+move to the the next output in the specified direction.
+
*Examples*:
-------------------------
bindsym mod+1 workspace 1
...
-------------------------
+==== Named workspaces
+
+Workspaces are identified by their name. So, instead of using numbers in the
+workspace command, you can use an arbitrary name:
+
+*Example*:
+-------------------------
+bindsym mod+1 workspace mail
+...
+-------------------------
+
+If you want the workspace to have a number *and* a name, just prefix the
+number, like this:
+
+*Example*:
+-------------------------
+bindsym mod+1 workspace 1: mail
+bindsym mod+2 workspace 2: www
+...
+-------------------------
+
+Note that the workspace will really be named "1: mail". i3 treats workspace
+names beginning with a number in a slightly special way. Normally, named
+workspaces are ordered the way they appeared. When they start with a number, i3
+will order them numerically.
+
[[resizingconfig]]
=== Resizing containers/windows
bindsym j resize shrink left
bindsym Shift+j resize grow left
- bindsym k resize grow bottom
- bindsym Shift+k resize shrink bottom
+ bindsym k resize grow down
+ bindsym Shift+k resize shrink down
- bindsym l resize shrink top
- bindsym Shift+l resize grow top
+ bindsym l resize shrink up
+ bindsym Shift+l resize grow up
bindsym semicolon resize grow right
bindsym Shift+semicolon resize shrink right
If you don’t already have your favorite way of generating such a status line
(self-written scripts, conky, …), then i3status is the recommended tool for
this task. It was written in C with the goal of using as few syscalls as
-possible to reduce the time your CPU is woken up from sleep states.
-
-Regardless of which application you use to generate the status line, you
-want to make sure that the application does one of the following things:
-
-1. Register as a dock window using EWMH hints. This will make i3 position the
- window above the workspace bar but below every other client. This is the
- recommended way, but in case of dzen2, for example, you need to check out
- the source of dzen2 from subversion, as the -dock option is not present
- in the released versions.
-2. Overlay the internal workspace bar. This method will not waste any space
- on the workspace bar, however, it is rather hackish. Just configure
- the output window to be over the workspace bar (say -x 200 and -y 780 if
- your screen is 800 px height).
-
-The planned solution for this problem is to make the workspace bar optional
-and switch to a third party application completely (dzen2 for example)
-which will then contain the workspace bar.
+possible to reduce the time your CPU is woken up from sleep states. Because
+i3status only spits out text, you need to combine it with some other tool, like
+i3bar. Use a pipe to connect them: +i3status | i3bar -d+.
+
+Regardless of which application you use to display the status line, you
+want to make sure that it registers as a dock window using EWMH hints. i3 will
+position the window either at the top or at the bottom of the screen, depending
+on which hint the application sets. With i3bar, you can use +-d+ or +-dbottom+
+for positioning it at the bottom and +-dtop+ to position it at the top of the
+screen.
=== Giving presentations (multi-monitor)
projects / i3 / i3 / blobdiff