# i3 config file (v4)+
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)+
It is possible and recommended to use comments in your configuration file to @@ -490,7 +498,7 @@ 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 @@ -498,6 +506,8 @@ is released.
If the --whole-window flag is given, the binding will also run when any part 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:
Example:
# Press $mod+o followed by either f, t, Esc or Return to launch firefox,
+# Press $mod+o followed by either f, t, Escape or Return to launch firefox,
# thunderbird or return to the default mode, respectively.
set $mode_launcher Launch: [f]irefox [t]hunderbird
bindsym $mod+o mode "$mode_launcher"
@@ -558,7 +568,7 @@ mode "$mode_launcher" {
bindsym f exec firefox
bindsym t exec thunderbird
- bindsym Esc mode "default"
+ bindsym Escape mode "default"
bindsym Return mode "default"
}
By default, window focus follows your mouse movements. However, if you have a -setup where your mouse usually is in your way (like a touchpad on your laptop -which you do not want to disable completely), you might want to disable focus -follows mouse and control focus only by using your keyboard. The mouse will -still be useful inside the currently active window (for example to click on -links in your browser window).
By default, window focus follows your mouse movements as the mouse crosses +window borders. However, if you have a setup where your mouse usually is in your +way (like a touchpad on your laptop which you do not want to disable +completely), you might want to disable focus follows mouse and control focus +only by using your keyboard. The mouse will still be useful inside the +currently active window (for example to click on links in your browser window).
Syntax:
If activated, marks on windows are drawn in their window decoration. However, -any mark starting with an underscore in its name (_) will not be drawn even if -this option is activated.
If activated, marks (see [vim_like_marks]) on windows are drawn in their window +decoration. However, any mark starting with an underscore in its name (_) will +not be drawn even if this option is activated.
The default for this option is yes.
Syntax:
Syntax:
output <output>+
output primary|<output>
Example:
Note that you might not have a primary output configured yet. To do so, run:
xrandr --output <output> --primary+
Syntax:
Use layout toggle split, layout stacking, layout tabbed, layout splitv 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 @@ -2076,7 +2103,8 @@ enable respectively floating disable (or floating toggle)
layout default|tabbed|stacking|splitv|splith -layout toggle [split|all]+layout toggle [split|all] +layout toggle [split|tabbed|stacking|splitv|splith] [split|tabbed|stacking|splitv|splith]â¦
Examples:
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:
Use the move command to move a container.
Syntax:
# Moves the container into the given direction. +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. + +*Syntax*:+
# Moves the container into the given direction. # The optional pixel argument specifies how far the # container should be moved if it is floating and # defaults to 10 pixels. -move <left|right|down|up> [<px> px] - -# Moves the container either to a specific location -# or to the center of the screen. If 'absolute' is +move <left|right|down|up> [<px> px]
# Moves the container either to a specific location +# or to the center of the screen. If absolute is # used, it is moved to the center of all outputs. -move [absolute] position [[<px> px] [<px> px]|center] - -# Moves the container to the current position of the +move [absolute] position <pos_x> [px] <pos_y> [px] +move [absolute] position center
# Moves the container to the current position of the # mouse cursor. Only affects floating containers. -move position mouse -
Examples:
# Move container to the left, bottom, top, right +*Examples*:+
# Move container to the left, bottom, top, right bindsym $mod+j move left bindsym $mod+k move down bindsym $mod+l move up -bindsym $mod+semicolon move right - -# Move container, but make floating containers +bindsym $mod+semicolon move right
# Move container, but make floating containers # move more than the default -bindsym $mod+j move left 20 px +bindsym $mod+j move left 20 px
# Move floating container to the center of all outputs +bindsym $mod+c move absolute position center
# Move container to the current position of the cursor +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: -# Move floating container to the center of all outputs -bindsym $mod+c move absolute position center ++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>>. -# Move container to the current position of the cursor -bindsym $mod+m move position mouse+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*:
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+
If you want a window to stick to the glass, i.e., have it stay on screen even if you switch to another workspace, you can use the sticky command. For example, this can be useful for notepads, a media player or a video chat @@ -2253,7 +2331,7 @@ for_window [instance=notepad] sticky enable
To change to a specific workspace, use the workspace command, followed by the number or name of the workspace. Pass the optional flag --no-auto-back-and-forth to disable [back_and_forth] for this specific call @@ -2313,7 +2391,7 @@ bindsym $mod+x move workspace to output right bindsym $mod+F1 [class="Firefox"] move workspace current
Workspaces are identified by their name. So, instead of using numbers in the workspace command, you can use an arbitrary name:
Example:
You can rename workspaces. This might be useful to start with the default numbered workspaces, do your work, and rename the workspaces afterwards to reflect whatâs actually on them. You can also omit the old name to rename @@ -2362,23 +2440,37 @@ i3-msg 'rename workspace "1: www" to "10: www"' i3-msg 'rename workspace to "2: mail"' bindsym $mod+r exec i3-input -F 'rename workspace to "%s"' -P 'New name: '
If you want to rename workspaces on demand while keeping the navigation stable, +you can use a setup like this:
Example:
bindsym $mod+1 workspace number "1: www" +bindsym $mod+2 workspace number "2: mail" +...+
If a workspace does not exist, the command workspace number "1: mail" will +create workspace "1: mail".
If a workspace with number 1 does already exist, the command will switch to this +workspace and ignore the text part. So even when the workspace has been renamed +to "1: web", the above command will still switch to it.
See [move_to_outputs] for how to move a container/workspace to a different RandR output.
To move a container to another RandR output (addressed by names like LVDS1 or VGA1) or to a RandR output identified by a specific direction (like left, right, up or down), there are two commands:
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:
To move a container to another container with a specific mark (see [vim_like_marks]), -you can use the following command.
The window will be moved right after the marked container in the tree, i.e., it ends up -in the same position as if you had opened a new window when the marked container was -focused. If the mark is on a split container, the window will appear as a new child -after the currently focused child within that container.
Syntax:
move window|container to mark <mark>+
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>>), +you can use the following command. + +The window will be moved right after the marked container in the tree, i.e., it ends up +in the same position as if you had opened a new window when the marked container was +focused. If the mark is on a split container, the window will appear as a new child +after the currently focused child within that container. + +*Syntax*:+
Example:
for_window [instance="tabme"] move window to mark target
If you want to resize containers/windows using your keyboard, you can use the resize command:
Syntax:
Often when in a multi-monitor environment, you want to quickly jump to a specific window. For example, while working on workspace 3 you may want to jump to your mail client to email your boss that youâve achieved some @@ -2460,7 +2565,7 @@ bindsym $mod+a [class="urxvt" title="VIM"] focus
This feature is like the jump feature: It allows you to directly jump to a specific window (this means switching to the appropriate workspace and setting focus to the windows). However, you can directly mark a specific window with @@ -2503,7 +2608,7 @@ unmark irssi
By default, i3 will simply print the X11 window title. Using title_format, this can be customized by setting the format to the desired output. This directive supports @@ -2561,7 +2666,7 @@ for_window [class="(?i)firefox"] title_format "<span foreground='red'>%tit
To change the border of the current client, you can use border normal to use the normal border (including window title), border pixel 1 to use a 1-pixel border (no window title) and border none to make the client borderless.
As described in http://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.
The debuglog command allows you to enable or disable debug logging at runtime. Debug logging is much more verbose than non-debug logging. This command does not activate shared memory logging (shmlog), and as such is most @@ -2632,7 +2737,7 @@ bindsym $mod+x debuglog toggle
You can make i3 reload its configuration file with reload. You can also restart i3 inplace with the restart command to get it out of some weird state (if that should ever happen) or to perform an upgrade without having to restart @@ -2647,7 +2752,7 @@ bindsym $mod+Shift+e exit
There are two commands to use any existing window as scratchpad window. move scratchpad will move a window to the scratchpad workspace. This will make it invisible until you show it again. There is no way to open that workspace. @@ -2682,7 +2787,7 @@ bindsym mod4+s [title="^Sup ::"] scratchpad show
There is a no operation command nop which allows you to override default behavior. This can be useful for, e.g., disabling a focus change on clicks with the middle mouse button.
There are two options in the configuration of each i3bar instance that can be changed during runtime by invoking a command through i3. The commands bar hidden_state and bar mode allow setting the current hidden_state @@ -2736,7 +2841,7 @@ bindsym $mod+Shift+b bar mode invisible bar-1
As you can see in the goal list on the website, i3 was specifically developed with support for multiple monitors in mind. This section will explain how to @@ -2759,7 +2864,7 @@ create an unlimited number of workspaces in i3 and tie them to specific screens, you can have the "traditional" approach of having X workspaces per screen by changing your configuration (using modes, for example).
To help you get going if you have never used multiple monitors before, here is a short overview of the xrandr options which will probably be of interest to you. It is always useful to get an overview of the current screen configuration. @@ -2822,7 +2927,7 @@ only what you can see in xrandr.
See also [presentations] for more examples of multi-monitor setups.
There are several things to configure in i3 which may be interesting if you have more than one monitor:
A very common thing amongst users of exotic window managers is a status line at some corner of the screen. It is an often superior replacement to the widget approach you have in the task bar of a traditional desktop environment.
When giving a presentation, you typically want the audience to see what you see on your screen and then go through a series of slides (if the presentation is simple). For more complex presentations, you might want to have some notes which only you can see on your screen, while the audience can only see the slides.
This is the simple case. You connect your computer to the video projector, turn on both (computer and video projector) and configure your X server to clone the internal flat panel of your computer to the video output:
This case is a bit harder. First of all, you should configure the VGA output somewhere near your internal flat panel, say right of it: