Difference between revisions of "I3"

From ArchWiki
Jump to: navigation, search
(Iconic fonts in the status bar)
(Undo revision 457021 by Lukeus Maximus (talk) - optional dependencies can be listed with pacman)
 
(370 intermediate revisions by 67 users not shown)
Line 2: Line 2:
 
[[Category:Tiling WMs]]
 
[[Category:Tiling WMs]]
 
[[Category:Dynamic WMs]]
 
[[Category:Dynamic WMs]]
[[ko:i3]]
+
[[ja:i3]]
[[ru:i3]]
+
[[ko:I3]]
[[zh-CN:i3]]
+
[[ru:I3]]
 +
[[zh-CN:I3]]
 +
{{Related articles start}}
 +
{{Related|Desktop environment}}
 +
{{Related|Display manager}}
 +
{{Related|File manager functionality}}
 +
{{Related|Window manager}}
 +
{{Related|Comparison of tiling window managers}}
 +
{{Related|Clipboard}}
 +
{{Related|Autostarting#Graphical}}
 +
{{Related articles end}}
 
[http://i3wm.org/ i3] is a dynamic [[Wikipedia:Tiling window manager|tiling window manager]] inspired by [[wmii]] that is primarily targeted at developers and advanced users.
 
[http://i3wm.org/ i3] is a dynamic [[Wikipedia:Tiling window manager|tiling window manager]] inspired by [[wmii]] that is primarily targeted at developers and advanced users.
  
Clients (windows) are organized in a tree data structure within containers. The tree branches via horizontal or vertical splits, and containers can also be set to tabbed or stacked layouts. Floating windows are available for corner cases that don't mix well with tiling, and remain on a separate layer above the tiled windows.
+
The stated goals for i3 include clear documentation, proper multi-monitor support, a tree structure for windows, and different modes like in [[vim]].
  
 
== Installation ==
 
== Installation ==
  
Install the {{Grp|i3}} [[Pacman#Installing package groups|package group]] from the [[official repositories]], which includes: {{Pkg|i3-wm}}, the window manager; {{Pkg|i3status}}, a package to write a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]]; and {{Pkg|i3lock}}, an improved screenlocker.
+
[[Install]] the {{Grp|i3}} [[Pacman#Installing package groups|package group]]. It includes the window manager {{Pkg|i3-wm}}, {{Pkg|i3status}} which writes a status line to i3bar through [[Wikipedia:Standard streams#Standard output (stdout)|stdout]], and {{Pkg|i3lock}}, a screen locker.
  
Additional packages are available in the [[Arch User Repository]]. Install {{AUR|i3-git}} for the development version.
+
Additional packages are available in the [[Arch User Repository]]. See the section [[#Patches]] for examples.
  
Install {{AUR|i3-gnome}} to add [[GNOME]] and X-sessions with {{Grp|i3}} running as the window manager. An Xsession starting just the window manager is included in {{Grp|i3}}.
+
=== Display manager ===
  
== Configuration ==
+
{{Pkg|i3-wm}} includes {{ic|i3.desktop}} as [[Xsession]] which starts the window manager. {{ic|i3-with-shmlog.desktop}} enables logs (useful for debugging). {{AUR|i3-gnome}} integrates {{ic|i3}} into [[GNOME]].
 +
 
 +
=== xinitrc ===
 +
 
 +
Edit [[Xinitrc]], and add:
  
Edit your {{ic|~/.xinitrc}} and add:
 
 
  exec i3
 
  exec i3
  
If you want i3 to log its output (useful for debugging), add this line to {{ic|~/.xinitrc}}:
+
To log the output from i3, add this line instead:
exec i3 -V >> ~/.i3/i3log 2>&1
+
 
 +
exec i3 -V >> ~/i3log-$(date +'%F-%k-%M-%S') 2>&1
 +
 
 +
== Usage ==
 +
 
 +
See the [http://i3wm.org/docs official documentation] for more information, namely the [http://i3wm.org/docs/userguide.html i3 User’s Guide].
 +
 
 +
=== Keybindings ===
 +
 
 +
In i3, commands are invoked with a modifier key, referred to as {{ic|$mod}}. This is {{ic|Alt}} (Mod1) by default, with {{ic|Super}} (Mod4) being a popular alternative. Super is the key usually represented on a keyboard as a Windows icon, or on an Apple keyboard as a Command key.
 +
 
 +
See the [http://i3wm.org/docs/refcard.html i3 reference card] and [http://i3wm.org/docs/userguide.html#_using_i3 Using i3] for the defaults. See [http://i3wm.org/docs/userguide.html#keybindings Keyboard bindings] to add new shortcuts.
 +
 
 +
Users of non-Qwerty keyboard layouts may wish to circumvent the "configuration wizard" as [[#Configuration wizard and alternative keyboard layouts|described below]].
 +
 
 +
=== Containers ===
 +
 
 +
i3 manages windows in a tree structure, with containers as building blocks. This structure branches with horizontal or vertical splits. Containers are tiled by default, but can be set to tabbed or stacked layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.
 +
 
 +
See [http://i3wm.org/docs/userguide.html#_tree i3 Tree] and [http://www.youtube.com/watch?v=AWA8Pl57UBY Containers and the tree data structure] for details.
 +
 
 +
=== Application launcher ===
 +
 
 +
i3 uses [[dmenu]] as an application launcher, which is bound by default to {{ic|$mod+d}}.
 +
 
 +
{{Pkg|i3-wm}} contains ''i3-dmenu-desktop'', a [[Wikipedia:Perl|Perl]] wrapper for ''dmenu'' which uses [[desktop entries]] to create a list of all installed applications. Alternatively, the package {{AUR|j4-dmenu-desktop-git}} can be used.
 +
 
 +
== Configuration ==
 +
 
 +
See [http://i3wm.org/docs/userguide.html#configuring Configuring i3] for details. The rest of this article assumes the ''i3'' configuration file to be in the folder {{ic|~/.config}}.
 +
 
 +
=== Configuration wizard and alternative keyboard layouts ===
 +
 
 +
When ''i3'' is first started, it offers to run the configuration wizard ''i3-config-wizard''. This tool creates {{ic|~/.config/i3/config}} by rewriting a template configuration file in {{ic|/etc/i3/config.keycodes}}. It makes two modifications to the default template:
 +
 
 +
# It asks the user to choose a default modifier key, which it adds to the template as a single line, like {{ic|set $mod Mod1}}; and
 +
# it replaces all ''bindcode'' lines with ''bindsym'' lines corresponding to the user's current keyboard layout.
 +
 
 +
Step 2 is designed to ensure that the four navigation shortcuts, {{ic|j}}, {{ic|k}}, {{ic|l}} and "semicolon" on a Qwerty keyboard, will be mapped to keysyms which have the same location, e.g. {{ic|h}}, {{ic|t}}, {{ic|n}}, {{ic|s}} on a [[Dvorak]] keyboard. The side-effect of this magic is that up to fifteen other keysyms may be remapped in ways which break the mnemonics - so that, for a Dvorak user, "restart" is bound to {{ic|$mod1+p}} instead of {{ic|$mod1+r}}, "split horizontally" is bound to {{ic|$mod1+d}} instead of {{ic|$mod1+h}}, and so on.
 +
 
 +
Therefore, users of alternate keyboard layouts who want straightforward key bindings, which match the bindings given in tutorials, may prefer to circumvent the "config wizard". This can be done by just copying {{ic|/etc/i3/config}} into {{ic|~/.config/i3/config}} (or {{ic|~/.i3/config}}), and editing that file.
  
If you use the Nvidia binary driver '''<302.17''' you need to add the {{ic|--force-xinerama}} flag to {{ic|~/.xinitrc}}. A detailed explanation can be found at [http://i3wm.org/docs/multi-monitor.html i3wm.org].
+
Note that a keycode-based configuration is also possible, e.g. for users who often switch between keyboard layouts, but want the i3 bindings to stay the same.
exec i3 --force-xinerama
+
  
If you have trouble with mapping keys (ie ; as semicolon), use {{Pkg|xorg-xev}} or see [[Extra Keyboard Keys]].
+
=== Colorschemes ===
$ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'
+
  
=== Status bar ===
+
The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.
  
The internal status bar, i3-''ws''bar, was deprecated and replaced by i3bar in i3 v4.0.
+
* {{App|i3-style|Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme|https://github.com/acrisci/i3-style|{{Aur|nodejs-i3-style}}{{Broken package link|{{aur-mirror|nodejs-i3-style}}}}}}
 +
* {{App|j4-make-config|Merge your config with a collection of themes or personal config parts, for example host-specific configuration, allowing quick changing of the theme and flexible, dynamic customization of the configuration|https://github.com/okraits/j4-make-config|{{Aur|j4-make-config-git}}}}
  
==== New method: i3bar ====
+
=== i3bar ===
  
Unlike i3-wsbar, which requires dzen2, i3bar does not have any dependencies other than {{Pkg|i3-wm}}. It can be used to view information generated by [[conky]] or i3status. For example (as of version 4.1):
+
In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:
  
{{hc|~/.i3/config|<nowiki>
+
{{hc|~/.config/i3/config|2=
 
bar {
 
bar {
 
     output            LVDS1
 
     output            LVDS1
Line 60: Line 112:
 
     }
 
     }
 
}
 
}
</nowiki>}}
+
}}
  
For further information see the [http://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] section of the official User Guide.
+
See the [http://i3wm.org/docs/userguide.html#_configuring_i3bar Configuring i3bar] for details.
  
==== Alternatives to i3status ====
+
==== i3bar alternatives ====
  
* [https://github.com/enkore/i3pystatus i3pystatus] - extensible i3status replacement with many modules and very flexible configuration. Multi-threaded and lock-up free. (AUR: {{AUR|i3pystatus-git}})
+
Some users may prefer panels such as those provided by conventional [[Desktop environment|Desktop Environments]]. This can be achieved within i3 by launching the panel application of choice during startup.
* [https://github.com/HarveyHunt/i3situation i3situation] – a pure python 3 replacement with features provided by multithreaded plugins.
+
* [https://github.com/ultrabug/py3status py3status] – an extensible i3status wrapper written in python
+
* [[dzen]] – often used with [[conky]] to create completely custom status bars
+
* [http://j4status.j4tools.org/ j4status] - j4status provides a status line using several plugin to retrieve information from your computer. j4status is a part of the [http://www.j4tools.org/ j4tools] - tools set to use with i3.
+
* [[h2status]] - trivial bash wrapper to i3status that nevertheless allows to conveniently write custom json entries, handle click events and asynchronously update the status bar.
+
  
==== Panel alternatives to status bar ====
+
For the [[Xfce#Panel|XFCE panel]]{{Broken section link}}, add the following line anywhere in {{ic|~/.config/i3/config}}:
  
Some users may prefer panels such as those provided by conventional [[Desktop_Environment|Desktop Environments]]. This can be achieved within i3 by launching the panel application of choice during startup.
+
exec --no-startup-id xfce4-panel --disable-wm-check
  
For the [[Xfce#Panel|XFCE panel]], add the following line to {{ic|~/.i3/config}}:
+
i3bar can be disabled by commenting the {{ic|<nowiki>bar{ }</nowiki>}} section of {{ic|~/.config/i3/config}}, or defining a keybind to toggle the bar:
exec --no-startup-id xfce4-panel
+
  
{{Note|Panel features that are specific to the [[Desktop_Environment|Desktop Environment]] (e.g., widgets for managing workspaces and sessions) will not work, though the normal i3 functionality will be unaffected.}}
+
{{hc|~/.config/i3/config|
 +
# bar toggle, hide or show
 +
bindsym $mod+m bar mode toggle
 +
}}
  
Disabling i3bar is as simple as commenting out the {{ic|bar{ &#125;}} section of {{ic|~/.i3/config}}.
+
=== i3status ===
 +
 
 +
Copy over the default configuration files to the home directory:
 +
 
 +
$ cp /etc/i3status.conf ~/.config/i3status/config
 +
 
 +
Not all plugins are defined in the default configuration and some configuration values may be invalid for your system, so the need to be updated accordingly. See {{ic|man i3status}} for details.
 +
 
 +
==== i3status replacements ====
 +
 
 +
* {{App|[[conky]]| Highly extensible system monitor. For usage with i3bar see [http://i3wm.org/docs/user-contributed/conky-i3bar.html this tutorial] |https://github.com/brndnmtthws/conky|{{Pkg|conky}}}}
 +
* {{App|[[i3blocks]]|Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.|https://github.com/vivien/i3blocks|{{AUR|i3blocks}}}}
 +
* {{App|i3pystatus|Extensible Python 3 status bar with many plugins and configuration options by default.|https://github.com/enkore/i3pystatus i3pystatus|{{AUR|i3pystatus-git}}}}
 +
* {{App|i3situation|Another Python 3 status bar generator.|https://github.com/HarveyHunt/i3situation|{{Aur|i3situation-git}}}}
 +
* {{App|j4status|Provides a statusline, configurable via plugins, and written in C. Extra plugins are provided by {{Aur|j4status-plugins-git}}.|http://j4status.j4tools.org/|{{Aur|j4status-git}}}}
 +
* {{App|goi3bar|i3status replacement written in Go. Configuration-file driven with several plugins, concurrency options, and rich plugin support.|https://github.com/denbeigh2000/goi3bar/|{{Aur|goi3bar-git}}}}
 +
* {{App|goblocks|Fast, lightweight i3status replacement written in Go.|https://github.com/davidscholberg/goblocks|{{Aur|goblocks}}}}
 +
* {{App|bumblebee-status|Theme-able Python status bar generator.|https://github.com/tobi-wan-kenobi/bumblebee-status}}
 +
* {{App|ty3status|i3status replacement written in Typescript. Built with first class support for javascript blocks.|https://github.com/mrkmg/ty3status|{{Aur|ty3status-git}}}}
 +
 
 +
==== i3status wrappers ====
 +
 
 +
* {{App|i3cat|A [[go]] based wrapper which can concatenate inputs from multiple external sources. It can handle click events and forwarding user specified signals to its subprocesses.|http://vincent-petithory.github.io/i3cat/|{{AUR|i3cat-git}}}}
 +
* {{App|py3status|An extensible i3status wrapper written in Python.|https://github.com/ultrabug/py3status|{{Aur|py3status}}}}
  
 
==== Iconic fonts in the status bar ====
 
==== Iconic fonts in the status bar ====
  
There is a patch for i3bar to make it properly support icons, but here we'll see how to take advantage of a couple of very complete iconic font sets in order to get really nice looking monochromatic icons in your status bar. Some ttf iconic font sets that are currently available in the AUR are:
+
''i3bar'' can be [[#Patches|patched]] for XBM icon support, but you can use iconic font sets instead.
  
* {{AUR|ttf-font-awesome}} that has a cheatsheet showing the Unicode point for each glyph here [http://fortawesome.github.io/Font-Awesome/cheatsheet/].
+
* {{App|ttf-font-awesome|Scalable vector icons that can be customized with CSS. A [http://fortawesome.github.io/Font-Awesome/cheatsheet/ cheatsheet] shows the Unicode point for each glyph.|http://fortawesome.github.io/Font-Awesome/|{{AUR|ttf-font-awesome}}}}
* {{AUR|ttf-font-icons}} provides the Icons font set, a non-overlapping and consistently sized mix of Awesome and Ionicons. This not only avoids the overlapping between Awesome and Ionicons but also some minor overlapping between the usual DejaVu Sans and Awesome. All in all it provides a ready to use solution for your status bar including lots of icons. The cheatsheet is here [https://www.dropbox.com/s/9iysh2i0gadi4ic/icons.pdf].
+
* {{App|ttf-font-icons|Non-overlapping and consistently sized mix of Awesome and Ionicons. This also avoids minor overlapping between DejaVu Sans and Awesome.|http://kageurufu.net/icons.pdf|{{AUR|ttf-font-icons}}}}.
  
Then you can combine these fonts by defining a font fallback sequence in your {{ic|~/.i3/config}}:
+
To combine fonts, define a font fallback sequence in your configuration file, separating fonts with {{ic|,}} like so:
 +
{{hc|~/.config/i3/config|2=
 +
bar {
 +
  ...
 +
  font pango:DejaVu Sans Mono, Icons 8
 +
  ...
 +
}
 +
}}
  
bar {
+
In accordance with [https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string pango syntax], font size is specified only once, at the end of the comma-separated list of font families. Setting a size for each font would cause all but the last font to be ignored.
  ...
+
  font pango:DejaVu Sans Mono, '''Icons''' 8
+
  ...
+
}
+
  
Notice that you have to first list the comma separated font families and then add only one size specification at the end of the string. Don't set a size for each family (even if it happens to be the same size for every family) and don't try to get the same result using multiple font directives, as the vertical alignments and heights of the different components of the i3bar will be wrong in unexpected ways. The correct pango descriptor syntax is as shown above.
+
Add icons to the format strings in {{ic|~/.config/i3status/config}} using the unicode numbers given in the cheatsheets linked above. The input method will vary between text editors. For instance, to insert the "heart" icon (unicode number f004):
  
Finally, you will have to enter the iconic glyphs into the format strings in {{ic|~/.i3status.conf}}. For this, use the unicode numbers given in the cheatsheets linked above. For example, if you're using vim you can type <C-v>uXXXX, where XXXX is the unicode hexadecimal number for the glyph.
+
{{Merge|Internationalization|Should be described in one place; see also [[ArchWiki:Requests#Input methods]].}}
  
=== Quickly jumping to open window ===
+
* in various gui text editors (e.g. [[gedit]], Leafpad) and terminals (e.g. GNOME Terminal, xfce4-terminal): {{ic|ctrl+shift+u}}, {{ic|f004}}, {{ic|Enter}}
 +
* in [[Emacs]]: {{ic|ctrl+x}}, {{ic|8}}, {{ic|Enter}}, {{ic|f004}}, {{ic|Enter}}
 +
* in [[Vim]] (while in insert mode): {{ic|Ctrl+v}}, {{ic|uf004}}
 +
* in [[urxvt]]: while holding {{ic|Ctrl+Shift}}, type {{ic|f004}}
  
* [https://github.com/proxypoke/quickswitch-for-i3 quickswitch-for-i3] – A Python utility to quickly change to and locate windows in i3
+
=== Terminal emulator ===
* [https://github.com/yiuin/i3-wm-scripts i3-wm-scripts] – search for and jump to windows with particular names matching regexp
+
* [https://github.com/ziberna/i3-py/tree/master/examples#winmenupy winmenupy] launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.
+
  
=== i3status ===
+
By default when pressing {{ic|$mod+Return}} it launches the {{ic|i3-sensible-terminal}} which is a script that invokes a terminal. See {{ic|man i3-sensible-terminal}} for the order terminals are invoked in.
  
First we need to copy over the default configuration files that we will be working with to our home directory.
+
To instead launch a terminal of choice, modify this line in {{ic|~/.config/i3/config}}:
  
  $ cp /etc/i3status.conf ~/.i3status.conf
+
  bindsym $mod+Return exec i3-sensible-terminal
  
{{Tip|The example configuration file uses {{ic|eth0}} and {{ic|wlan0}} as interface names, see [[Network Configuration#Device names]] if they do not match with your system.}}
+
Alternatively, set the {{ic|$TERMINAL}} [[environment variable]].
  
==== Temperature status ====
+
== Tips and tricks ==
  
If you would like to add your CPU temperature to the i3status bar simply add these lines to {{ic|~/.i3status.conf}}:
+
=== Advanced window navigation ===
  
{{hc|~/.i3status.conf|2=
+
See [http://www.slackword.net/?p=657 i3 window Navigation Tips].
order += "cpu_temperature 0"
+
 
cpu_temperature 0 {
+
=== Jump to open window ===
        format = "T: %degrees °C"
+
 
    max_threshold = 65
+
*{{App|quickswitch-i3|Python utility to quickly change to and locate windows in i3|https://github.com/proxypoke/quickswitch-for-i3|{{Aur|quickswitch-i3}}}}
        path = "/sys/devices/platform/coretemp.0/temp1_input"
+
*{{App|i3-wm-scripts|search for and jump to windows with particular names matching regexp|https://github.com/yiuin/i3-wm-scripts||}}
}
+
*{{App|winmenupy|Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.|https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py||}}
 +
*{{App|[[rofi]]|Search and jump to open and scratchpad window|https://davedavenport.github.io/rofi/|{{Pkg|rofi}}}}
 +
 
 +
=== Jump to urgent window ===
 +
 
 +
Add to {{ic|.i3/config}}: [https://faq.i3wm.org/question/853/how-to-jump-to-urgent-workspace/]
 +
 
 +
bindsym $mod+x [urgent=latest] focus
 +
 
 +
=== Save and restore the window layout ===
 +
 
 +
From version 4.8, and onward ''i3'' can save and restore workspace layouts. To do this, the following packages are needed: {{Pkg|perl-anyevent-i3}} and {{Pkg|perl-json-xs}} from the [[official repositories]].
 +
 
 +
{{note| This section only provides quick tutorial on how to save the current window layout of a single workspace and how to restore it for later use. Refer to the [http://i3wm.org/docs/layout-saving.html official documentation] for more details}}
 +
 
 +
==== Save the current window layout of a single workspace ====
 +
 
 +
To save the current window layout, follow these steps:
 +
 
 +
# First, execute various commands to open windows in a preferred workspace and resize them if needed. Make sure to write down each executed command for each window.
 +
# Now, in a new workspace, open a terminal and run the following: {{bc|i3-save-tree --workspace N > ~/.i3/workspace_N.json}} where N is the number of the preferred workspace. This will save the current layout of workspace N to the file {{ic|~/.i3/workspace_N.json}}.
 +
# The newly created file needs to be edited, however this may be done with the following commands: {{bc|<nowiki>tail -n +2 ~/.i3/workspace_N.json | fgrep -v '// splitv' | sed 's|//||g' > ~/.i3/workspace_N.json</nowiki>}}
 +
 
 +
==== Restore the window layout of the workspace ====
 +
 
 +
There are two ways to restore the layout of the workspace: by writing a script, or by editing {{ic|~/.i3/config}} to automatically load the layout. In this section only the first case will be considered, refer to the [http://i3wm.org/docs/layout-saving.html#_restoring_the_layout official documentation] for the second case.
 +
 
 +
To restore the saved layout in the previous section, write a file named {{ic|load_layout.sh}} with the following contents:
 +
 
 +
* The starting lines:
 +
 
 +
{{hc|head=~/load_layout.sh|output=
 +
#!/bin/bash
 +
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"
 
}}
 
}}
  
If the temperature column complains that it cannot get the temperature value then change the path line to:
+
where M is the number of the workspace in which you would like to load the previously saved layout and N is the number of workspace saved in the previous section.
 +
* And the commands used in the previous section to get the preferred windows, but enclosed in parentheses and with an ampersand appended before the last parentheses.
  
path = "/sys/class/thermal/thermal_zone0/temp"
+
For example, if the saved layout contained three {{ic|uxterm}} windows:
  
=== Volume manager ===
+
{{hc|head=~/load_layout.sh|output=
 +
#!/bin/bash
  
To enable easy management of your system volume, you can install a volume manager applet such as {{AUR|pa-applet-git}} from the [[AUR]].  This should also allow you to use your keyboards volume up, volume down, and mute keys as well as using the applet directly to manage your volume.  Once it is installed add the following line to your {{ic|~/.i3/config}} to auto start the applet:
+
# First we append the saved layout of worspace N to workspace M
 +
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"
  
exec /usr/bin/pa-applet
+
# And finally we fill the containers with the programs they had
 +
(uxterm &)
 +
(uxterm &)
 +
(uxterm &)
 +
}}
  
=== Network manager ===
+
Then set the file as executable:
  
If you would like to use {{Pkg|network-manager-applet}} to manage your network connections, follow the instructions in [[NetworkManager]].
+
chmod u+x ~/load_layout.sh
  
Then add the the following line to your {{ic|~/.i3/config}} to automatically start the Network Manager applet in your system tray
+
And finally, the layout of worskpace N can be loaded onto to workspace M by running:
  
  exec /usr/bin/nm-applet
+
  ~/load_layout.sh
  
=== Workspace names ===
+
{{tip|Adding {{ic|bindsym $mod+g exec ~/load_layout.sh}} to {{ic|~/.i3/config}} and restarting i3 will bind Mod+g to run the above script.}}
  
Although it is not required, many people prefer naming frequently used workspaces. First you need to determine which monitor you want the workspace to open to. Simply type {{ic|xrandr}} into a terminal and it will show you the available display ports. Some common ones are LVDS1 for laptops or VGA1, HDMI1, HDMI2, etc for external monitors. If you are using [[Multihead#Xinerama|Xinerama]] instead use the outputs xinerama-0, xinerama-1, etc. Add your workspace names to {{ic|~/.i3/config}} You also need to modify the corresponding lines to switch to your workspaces as well as moving focused containers to those workspaces.
+
{{note|If the above script does not work properly, refer to the [http://i3wm.org/docs/layout-saving.html#_editing_layout_files  official documentation]. The ''swallows'' sections of {{ic|~/.i3/workspace_N.json}} needs to be manually edited.}}
  
# Workspace names
+
=== Scratchpad containers ===
workspace "1:Web" output LVDS1
+
workspace "2:Mail" output LVDS1
+
workspace "3:Irc" output LVDS1
+
workspace "4:Shell" output LVDS1
+
  
# switch to workspace
+
By default, [http://i3wm.org/docs/userguide.html#_scratchpad scratchpads] only contain a single window. However, containers can also be made a scratchpad.
bindsym $mod+1 workspace 1:Web
+
bindsym $mod+2 workspace 2:Mail
+
bindsym $mod+3 workspace 3:Irc
+
bindsym $mod+4 workspace 4:Shell
+
  
# move focused container to workspace
+
Create a new container (for example, {{ic|Mod+Enter}}), split it ({{ic|Mod+v}}) and create another container. Focus the parent ({{ic|Mod+a}}), split in the opposite direction ({{ic|Mod+h}}), and create again.
bindsym $mod+Shift+1 move container to workspace 1:Web
+
bindsym $mod+Shift+2 move container to workspace 2:Mail
+
bindsym $mod+Shift+3 move container to workspace 3:Irc
+
bindsym $mod+Shift+4 move container to workspace 4:Shell
+
  
=== Launching programs on specific workspaces ===
+
Focus the first container (with focus parent as needed), make the window floating ({{ic|Mod+Shift+Space}}), and move it to the scratchpad ({{ic|Mod+Shift+-}}). You can now split containers to preference.
  
To maximize efficiency you can setup certain programs to automatically launch to a specific workspace.  This can be accomplished one of two ways. You could use the {{ic|assign}} command so when you manually launch a program it is directed to a the workspace you assigned. An example would be:
+
{{Note|Containers cannot be resized individually in floating windows. Resize the containers before making windows floating.}}
 +
{{Tip|When only using terminal applications, consider a multiplexer such as [[tmux]] instead.}}
  
# Assign URxvt terminals to workspace 2
+
See also [https://faq.i3wm.org/question/138/multiple-scratchpad/i3] for multiple scratchpads.
assign [class="URxvt"] 2
+
  
Or if you have renamed the workspaces like the above examples then you must set the new workspace name instead of the number:
+
=== Screensaver and power management ===
 +
 
 +
With [[Power management#xss-lock]] you can register a screenlocker for your i3 session. The {{ic|-time}} option locks the screen after a given time period.
 +
 
 +
xautolock -time 10 -locker "i3lock -i 'background_image.png'" &
 +
 
 +
A [[systemd]] service file can be used to lock the screen before the system is being sent to sleep or hibernation state. See [[Power management#Suspend/resume service files]]. Note that i3lock requires the type of the service to be {{ic|forking}}.
 +
 
 +
See also [[DPMS]].
 +
 
 +
=== Shutdown, reboot, lock screen ===
 +
 
 +
Key combinations for shutdown, reboot and screenlock can be added to {{ic|~/.config/i3/config}}. The below example assumes you have {{Pkg|polkit}} installed to allow unprivileged users to run [[systemd#Power_management|power management]] commands.
 +
 
 +
{{bc|
 +
set $Locker i3lock && sleep 1
 +
 
 +
set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown
 +
mode "$mode_system" {
 +
    bindsym l exec --no-startup-id $Locker, mode "default"
 +
    bindsym e exec --no-startup-id i3-msg exit, mode "default"
 +
    bindsym s exec --no-startup-id $Locker && systemctl suspend, mode "default"
 +
    bindsym h exec --no-startup-id $Locker && systemctl hibernate, mode "default"
 +
    bindsym r exec --no-startup-id systemctl reboot, mode "default"
 +
    bindsym Shift+s exec --no-startup-id systemctl poweroff -i, mode "default" 
 +
 
 +
    # back to normal: Enter or Escape
 +
    bindsym Return mode "default"
 +
    bindsym Escape mode "default"
 +
}
 +
 
 +
bindsym $mod+Pause mode "$mode_system"
 +
}}
 +
 
 +
Once completed, you will be presented with a prompt whenever you press {{ic|$mod+pause}}. For more complex behaviour, use a separate script, and refer to it in the mode. [https://gist.github.com/anonymous/c8cd0a59bf4acb273068]
 +
 
 +
{{Note|1=<br>
 +
* {{ic|sleep 1}} adds a small delay to prevent possible race conditions with suspend [https://bugs.launchpad.net/ubuntu/+source/unity-2d/+bug/830348]
 +
* The {{ic|-i}} argument for {{ic|systemctl poweroff}} causes a shutdown even if other users are logged-in (this requires {{Pkg|polkit}}), or when ''logind'' (wrongly) assumes so. [https://bugs.freedesktop.org/show_bug.cgi?id=62676]
 +
}}
 +
 
 +
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].
 +
 
 +
===External displays manual management===
 +
 
 +
Thanks to [[xrandr]] there are many ways to easily manage systems displays. The below example integrates it in the i3 config file, and behave as the Power Management section above.
 +
 
 +
Here a laptop with both VGA and HDMI outputs will use a menu selection to switch them On/Off:
 +
 
 +
## Manual management of external displays
 +
# Set the shortcuts and what they do
 +
set $mode_display Ext Screen (v) VGA ON, (h) HDMI ON, (x) VGA OFF, (y) HDMI OFF
 +
mode "$mode_display" {
 +
    bindsym v exec --no-startup-id xrandr --output VGA1 --auto --right-of LVDS1, mode "default"
 +
    bindsym h exec --no-startup-id xrandr --output HDMI1 --auto --right-of LVDS1, mode "default"
 +
    bindsym x exec --no-startup-id xrandr --output VGA1 --auto --off, mode "default"
 +
    bindsym y exec --no-startup-id xrandr --output HDMI1 --auto --off, mode "default"
 +
 +
    # back to normal: Enter or Escape
 +
    bindsym Return mode "default"
 +
    bindsym Escape mode "default"
 +
}
 +
# Declare here the shortcut to bring the display selection menu
 +
bindsym $mod+x mode "$mode_display"
 +
 
 +
Any window that is still open in a switched Off display will automatically come back to the remaining active display.
  
# Assign URxvt terminals to workspace 4:Shell
+
The simplest way to determine names of your devices is to plug the device you wish to use and run:
assign [class="URxvt"] 4:Shell
+
  
{{Note|To be able to determine the class, title, instance, etc of an open window you can use the tool {{ic|xprop}} by installing the package {{Pkg|xorg-xprop}} from the Extra repository.}}
+
$ xrandr --query
  
Alternatively you can change to your target workspace with {{ic|i3-msg}} then have your frequently used programs start automatically with the {{ic|exec}} command:
+
which will output the available, recognized devices and their in-system names to set your config file appropriately.
  
exec --no-startup-id i3-msg 'workspace 1:Web; exec /usr/bin/firefox'
+
Refer to the [[xrandr]] page or man page for the complete list of available options, the [http://i3wm.org/docs/userguide.html i3 userguide] and/or the [https://www.reddit.com/r/i3wm i3 FAQ on reddit] for more info.
exec --no-startup-id i3-msg 'workspace 2:Mail; exec urxvt -name Mail -e /usr/bin/mutt'
+
exec --no-startup-id i3-msg 'workspace 3:Irc; exec /usr/bin/urxvt -name irssi -e /usr/bin/irssi'
+
exec --no-startup-id i3-msg 'workspace 4:Shell; exec /usr/bin/urxvt'
+
  
 
=== Tabbed or stacked web-browsing ===
 
=== Tabbed or stacked web-browsing ===
Line 195: Line 360:
 
Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.
 
Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.
  
To let i3 manage your tab-less web-browser, in this example for [[uzbl]], add the following line to your {{ic|~/.i3/config}}
+
To let i3 manage your tab-less web-browser, in this example for [[uzbl]], add the following line to your {{ic|~/.config/i3/config}}
  
 
  for_window [class="Uzbl-core"] focus child, layout stacking, focus
 
  for_window [class="Uzbl-core"] focus child, layout stacking, focus
Line 205: Line 370:
 
  for_window [class="Uzbl-core"] focus child, layout tabbed, focus
 
  for_window [class="Uzbl-core"] focus child, layout tabbed, focus
  
=== Desktop wallpaper ===
+
=== Workspace variables ===
  
To be able to manage the desktop wallpaper, you need a lightweight image viewer like [[Feh]] or [[Nitrogen]]. Install feh with the command {{ic|# pacman -S feh}}. Then you can set your wallpaper with the following command:
+
As workspaces are defined multiple times in i3, assigning workspace variables can be helpful. For example:
  
  $ feh --bg-scale /path/to/image.file
+
  set $WS1 term
 +
set $WS2 web
 +
set $WS3 misc
 +
set $WS4 media
 +
set $WS5 code
  
To have feh set your image to the Desktop Wallpaper add the following line to your {{ic|~/.i3/config}}
+
Then replace workspace names with their matching variables:
  
  exec --no-startup-id sh ~/.fehbg
+
  bindsym $mod+1          workspace $WS1
 +
...
 +
bindsym $mod+Shift+1    move container to workspace $WS1
  
=== Terminal emulator ===
+
See [http://i3wm.org/docs/userguide.html#_changing_named_workspaces_moving_to_workspaces Changing named workspaces] for more information.
  
By default when you press $mod+Return it launches the i3-sensible-terminal which is a script that invokes a terminal.  It attempts to start one of these terminals in the following order: $TERMINAL urxvt rxvt terminator Eterm aterm xterm gnome-terminal roxterm xfce4-terminal.  You can force it to launch your terminal of choice by modifying the line {{ic|bindsym $mod+Return exec i3-sensible-terminal}}
+
=== Correct handling of floating dialogs ===
  
=== Scratchpad ===
+
While dialogs should open in floating mode by default [http://i3wm.org/docs/userguide.html#_floating], many still open in tiling mode. To change this behaviour, check the dialog's {{ic|WM_WINDOW_ROLE}} with {{pkg|xorg-xprop}} and add the correct rules to {{ic|~/.i3/config}} (using [http://www.pcre.org/ pcre] syntax):
  
Having a scratchpad to jot down or paste notes quickly is very handy! i3 has a feature that allows you to move a window to a scratchpad workspace. Basically it will be hidden from view until you recall it with the {{ic|scratchpad show}} command. To send a focused window to the scratchpad with $mod+Shift+minus or to recall it with $mod+minus enter these lines into your {{ic|~/.i3/config}}
+
  for_window [window_role="pop-up"] floating enable
 +
for_window [window_role="task_dialog"] floating enable
  
# Make the currently focused window a scratchpad
+
You can also use title rules and regular expressions:
bindsym $mod+Shift+minus move scratchpad
+
+
# Show the first scratchpad window
+
bindsym $mod+minus scratchpad show
+
  
You can start your favorite editor (ie Gedit, vim, nano, etc) on startup and have it automatically moved to the scratchpad workspace to quickly recall it when needed. The following example when placed in {{ic|~/.i3/config}} shows how you can start the urxvt terminal, have it launch the nano editor, and then move it to the scratchpad:
+
for_window [title="Preferences$"] floating enable
  
# starting a specially named term automatically
+
or {{ic|WM_CLASS}}:
exec --no-startup-id urxvt -name scratchpad -e /usr/bin/nano
+
# move this to scratchpad, if active
+
for_window [class="URxvt" instance="scratchpad"] move scratchpad
+
  
=== Shutdown, reboot, lock screen ===
+
for_window [class="(?i)mplayer"] floating enable
As there are no Shutdown, Reboot, or Lock Screen buttons, we can add some hotkey combinations to help us out.  First we need to create this script and save it as {{ic|i3exit}}.  Remember to make it executable with {{ic|chmod +x}} and to place it somewhere in your $PATH.
+
  
{{bc|<nowiki>
+
=== Network Download/Upload speed on statusbar ===
#!/bin/sh
+
lock() {
+
    i3lock
+
}
+
  
case "$1" in
+
You might adapt this upstream [http://code.stapelberg.de/git/i3status/tree/contrib/measure-net-speed.bash script]. For that,
    lock)
+
        lock
+
        ;;
+
    logout)
+
        i3-msg exit
+
        ;;
+
    suspend)
+
        lock && systemctl suspend
+
        ;;
+
    hibernate)
+
        lock && systemctl hibernate
+
        ;;
+
    reboot)
+
        systemctl reboot
+
        ;;
+
    shutdown)
+
        systemctl poweroff
+
        ;;
+
    *)
+
        echo "Usage: $0 {lock|logout|suspend|hibernate|reboot|shutdown}"
+
        exit 2
+
esac
+
  
exit 0
+
* rename both network cards according to your system (use {{ic|ip addr}})
</nowiki>}}
+
* find them on {{ic|/sys/devices}} then replace them appropriately:
 +
$ find /sys/devices -name ''network_interface''
  
Now add the following lines to your {{ic|~/.i3/config}} Once completed you will be presented with a prompt whenever you press {{ic|$mod+pause}}.
+
{{Tip|Use {{ic|/sys/class/net/''interface''/statistics/}} to not depend on PCI location.}}
  
set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown
+
Now, just save the script in a suitable place (for example {{ic|~/.config/i3}}) and point your status program to it.
mode "$mode_system" {
+
    bindsym l exec --no-startup-id i3exit lock, mode "default"
+
    bindsym e exec --no-startup-id i3exit logout, mode "default"
+
    bindsym s exec --no-startup-id i3exit suspend, mode "default"
+
    bindsym h exec --no-startup-id i3exit hibernate, mode "default"
+
    bindsym r exec --no-startup-id i3exit reboot, mode "default"
+
    bindsym Shift+s exec --no-startup-id i3exit shutdown, mode "default" 
+
+
    # back to normal: Enter or Escape
+
    bindsym Return mode "default"
+
    bindsym Escape mode "default"
+
}
+
bindsym $mod+Pause mode "$mode_system"
+
  
=== Screensaver and power management ===
+
== Patches ==
  
You can use [[Display_Power_Management_Signaling|DPMS]] to blank your screen or to suspend/poweroff your monitor. Adding the following line to your {{ic|~/.i3/config}} will suspend your monitor after 10 minutes.
+
{{Merge|#Installation|One package does not warrant a separate section}}
  
exec --no-startup-id xset dpms 600
+
Packages with patches not merged upstream are available in the [[AUR]]:
  
With {{AUR|xss-lock}} you can register a screenlocker for your i3 session. xss-lock subscribes to the systemd-events {{ic|suspend}}, {{ic|hibernate}}, {{ic|lock-session}}, and {{ic|unlock-session}} with appropriate actions (run locker and wait for user to unlock or kill locker). It also reacts to the [[Display Power Management Signaling#xset screen-saver control|X screensaver]] and runs or kills the locker in response to the x-server signals. Start xss-lock in your autostart like this:
+
* {{App|i3-wm-iconpatch|Titlebar icon support|https://github.com/ashinkarov/i3-extras|{{AUR|i3-wm-iconpatch}}}}
xss-lock -- i3lock -i ''background_image'' &
+
  
== Usage ==
+
== Troubleshooting ==
  
See the [http://i3wm.org/docs official documentation] on this subject for more information: [http://i3wm.org/docs/userguide.html i3 User’s Guide]
+
=== General ===
  
In i3, commands are invoked using a modifier key, which is referred to as $mod. This is the Alt key (Mod1) by default, with the Windows key (Mod4) being a popular alternative.
+
In many cases, bugs are fixed in the development versions {{AUR|i3-git}} and {{AUR|i3status-git}}, and upstream will ask to reproduce any errors with this version. [http://i3wm.org/docs/debugging.html] See also [[Debug - Getting Traces#General]].
  
=== Default keybindings ===
+
=== Buttons in the i3 message bar do not work ===
  
(Many thanks for Funtoo Linux team foor the excellent wiki (http://www.funtoo.org/I3_Tiling_Window_Manager))
+
Buttons such as "Edit config" in {{ic|i3-nagbar}} call {{ic|i3-sensible-terminal}}, so make sure your [[#Terminal_emulator|Terminal emulator]] is recognized by i3.
  
{| border="1"
+
=== Faulty line wraps in tiled terminals ===
! Key !! Command
+
|-
+
|$mod + Enter || Open terminal
+
|-
+
|$mod + A || Focus Parent
+
|-
+
|$mod + S || Stacked Layout
+
|-
+
|$mod + W || Tabbed Layout
+
|-
+
|$mod + E || Default Layout
+
|-
+
|$mod + SpaceBar || Focus tiling/floating
+
|-
+
|$mod + D || dmenu
+
|-
+
|$mod + H || Split Horizontal
+
|-
+
|$mod + V || Split Vertically
+
|-
+
|$mod + J || Left
+
|-
+
|$mod + K || Down
+
|-
+
|$mod + J || Up
+
|-
+
|$mod + ; || Right
+
|-
+
|$mod + Shift + Q || Kill window
+
|-
+
|$mod + Shift + E || Exit i3
+
|-
+
|$mod + Shift + C || Reload i3config without restarting
+
|-
+
|$mod + Shift + R || Restart i3 (reloads i3config without exiting i3)
+
|-
+
|$mod + Shift + J || Move left
+
|-
+
|$mod + Shift + K || Move down
+
|-
+
|$mod + Shift + L || Move up
+
|-
+
|$mod + Shift + : || Move right
+
|-
+
|$mod + Shift + SpaceBar || Toggle tiling/floating
+
|}
+
  
=== Application launcher ===
+
i3 v4.3 and higher ignore size increment hints for tiled windows [https://www.mail-archive.com/i3-discuss@i3.zekjur.net/msg00709.html]. This may cause terminals to wrap lines prematurely, amongst other issues. As a workaround, make the offending window floating, before tiling it again.
  
i3 currently uses [[dmenu]] as a application launcher, which is bound by default to {{ic|$mod+d}}.
+
=== Mouse cursor remains in waiting mode ===
  
By default i3-dmenu-desktop is used as a wrapper for dmenu. i3-dmenu-desktop creates a list of all installed applications via their .desktop files. There is a rewrite of this perl script called {{AUR|j4-dmenu-desktop-git}}, which is a near-drop-in replacement for the script shipped with i3, but much faster.
+
When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.
  
=== Clipboard (copy & paste issues) ===
+
To solve this for a particlar application, use the {{ic|--no-startup-id}} parameter, for example:
 +
exec --no-startup-id ~/script
 +
bindsym $mod+d exec --no-startup-id dmenu_run
  
By default, when you close a window, the buffer with the clipboard info will disappear. You have to use a clipboard manager like {{Pkg|clipit}} to avoid that.
+
To disable this animation globally, see [[Cursor themes#Create links to missing cursors]].
 +
 
 +
=== Unresponsive key bindings ===
 +
 
 +
Some tools such as [[Taking_a_screenshot#scrot|scrot]] may not work when used with a regular key binding (executed after key press). In those cases, execute commands after key release with the {{ic|--release}} argument [http://i3wm.org/docs/userguide.html#keybindings]:
 +
 
 +
bindsym --release Print exec --no-startup-id scrot
 +
bindsym --release Shift+Print exec --no-startup-id scrot -s
 +
 
 +
=== Tearing ===
 +
 
 +
i3 does [https://github.com/i3/i3/issues/661 not properly implement double buffering] hence tearing or flickering may occur. To prevent this, install and configure [[compton]]. [https://faq.i3wm.org/question/3279/do-i-need-a-composite-manager-compton.1#post-id-3282]
 +
 
 +
=== Tray icons not visible ===
 +
 
 +
The {{ic|tray_output primary}} directive may require setting a primary output with ''xrandr'', specifying the output explicitly or simply removing this directive. [https://github.com/i3/i3/issues/1144] See [[Xrandr]] for details. The default configuration created by i3-config-wizard no longer adds this directive to the configuration from i3 4.12.
  
 
== See also ==
 
== See also ==
  
* [http://i3wm.org/docs/userguide.html i3 User Guide]
 
* [[Comparison of Tiling Window Managers]]
 
 
* [http://i3wm.org Official website]
 
* [http://i3wm.org Official website]
* [http://code.stapelberg.de/git/i3 Source code]
+
* [http://www.funtoo.org/I3_Tiling_Window_Manager funtoo Wiki]
* [https://github.com/ashinkarov/i3-extras Collection of scripts and patches]
+
* [http://code.stapelberg.de/git/i3 i3 Source code]
 +
* [https://github.com/ashinkarov/i3-extras i3-extras] - Collection of scripts and patches
 +
* [https://github.com/acrisci/i3ipc-glib i3ipc-glib] - A library for i3 extensions
 +
* [https://github.com/veelenga/i3ipc-ruby i3ipc-ruby] - An improved library for i3 extensions in Ruby
 +
* [http://www.j4tools.org/ j4tools] - non-official tools designed to work with i3
  
 
'''Arch Linux Forums'''
 
'''Arch Linux Forums'''
 
* [https://bbs.archlinux.org/viewtopic.php?id=99064 The i3 thread] - A general discussion about i3
 
* [https://bbs.archlinux.org/viewtopic.php?id=99064 The i3 thread] - A general discussion about i3
 
* [https://bbs.archlinux.org/viewtopic.php?id=103369 i3 desktop screenshots and config sharing]
 
* [https://bbs.archlinux.org/viewtopic.php?id=103369 i3 desktop screenshots and config sharing]
 +
 +
'''Screencasts'''
 +
* [http://www.youtube.com/watch?v=Wx0eNaGzAZU i3 window manager v4.1 screencast]
 +
* [https://www.youtube.com/watch?v=j1I63wGcvU4&index=1&list=PL5ze0DjYv5DbCv9vNEzFmP6sU7ZmkGzcf i3 window manager v4.1X screencasts]

Latest revision as of 19:12, 17 November 2016

i3 is a dynamic tiling window manager inspired by wmii that is primarily targeted at developers and advanced users.

The stated goals for i3 include clear documentation, proper multi-monitor support, a tree structure for windows, and different modes like in vim.

Installation

Install the i3 package group. It includes the window manager i3-wm, i3status which writes a status line to i3bar through stdout, and i3lock, a screen locker.

Additional packages are available in the Arch User Repository. See the section #Patches for examples.

Display manager

i3-wm includes i3.desktop as Xsession which starts the window manager. i3-with-shmlog.desktop enables logs (useful for debugging). i3-gnomeAUR integrates i3 into GNOME.

xinitrc

Edit Xinitrc, and add:

exec i3

To log the output from i3, add this line instead:

exec i3 -V >> ~/i3log-$(date +'%F-%k-%M-%S') 2>&1

Usage

See the official documentation for more information, namely the i3 User’s Guide.

Keybindings

In i3, commands are invoked with a modifier key, referred to as $mod. This is Alt (Mod1) by default, with Super (Mod4) being a popular alternative. Super is the key usually represented on a keyboard as a Windows icon, or on an Apple keyboard as a Command key.

See the i3 reference card and Using i3 for the defaults. See Keyboard bindings to add new shortcuts.

Users of non-Qwerty keyboard layouts may wish to circumvent the "configuration wizard" as described below.

Containers

i3 manages windows in a tree structure, with containers as building blocks. This structure branches with horizontal or vertical splits. Containers are tiled by default, but can be set to tabbed or stacked layouts, as well as made floating (such as for dialog windows). Floating windows are always on top.

See i3 Tree and Containers and the tree data structure for details.

Application launcher

i3 uses dmenu as an application launcher, which is bound by default to $mod+d.

i3-wm contains i3-dmenu-desktop, a Perl wrapper for dmenu which uses desktop entries to create a list of all installed applications. Alternatively, the package j4-dmenu-desktop-gitAUR can be used.

Configuration

See Configuring i3 for details. The rest of this article assumes the i3 configuration file to be in the folder ~/.config.

Configuration wizard and alternative keyboard layouts

When i3 is first started, it offers to run the configuration wizard i3-config-wizard. This tool creates ~/.config/i3/config by rewriting a template configuration file in /etc/i3/config.keycodes. It makes two modifications to the default template:

  1. It asks the user to choose a default modifier key, which it adds to the template as a single line, like set $mod Mod1; and
  2. it replaces all bindcode lines with bindsym lines corresponding to the user's current keyboard layout.

Step 2 is designed to ensure that the four navigation shortcuts, j, k, l and "semicolon" on a Qwerty keyboard, will be mapped to keysyms which have the same location, e.g. h, t, n, s on a Dvorak keyboard. The side-effect of this magic is that up to fifteen other keysyms may be remapped in ways which break the mnemonics - so that, for a Dvorak user, "restart" is bound to $mod1+p instead of $mod1+r, "split horizontally" is bound to $mod1+d instead of $mod1+h, and so on.

Therefore, users of alternate keyboard layouts who want straightforward key bindings, which match the bindings given in tutorials, may prefer to circumvent the "config wizard". This can be done by just copying /etc/i3/config into ~/.config/i3/config (or ~/.i3/config), and editing that file.

Note that a keycode-based configuration is also possible, e.g. for users who often switch between keyboard layouts, but want the i3 bindings to stay the same.

Colorschemes

The configuration file allows for customization of window decoration colors, but the syntax makes it impractical to create or share themes. There are several projects which make this easier and include a variety of user-contributed themes.

  • i3-style — Modifies your config in place from a theme stored in a JSON object, designed for frequently tweaking or changing a colorscheme
https://github.com/acrisci/i3-style || nodejs-i3-styleAUR[broken link: archived in aur-mirror]
  • j4-make-config — Merge your config with a collection of themes or personal config parts, for example host-specific configuration, allowing quick changing of the theme and flexible, dynamic customization of the configuration
https://github.com/okraits/j4-make-config || j4-make-config-gitAUR

i3bar

In addition to showing workspace information, i3bar can act as an input for i3status or an alternative, such as those mentioned in the next section. For example:

~/.config/i3/config
bar {
    output            LVDS1
    status_command    i3status
    position          top
    mode              hide
    workspace_buttons yes
    tray_output       none
    
    font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1

    colors {
        background #000000
        statusline #ffffff

        focused_workspace  #ffffff #285577
        active_workspace   #ffffff #333333
        inactive_workspace #888888 #222222
        urgent_workspace   #ffffff #900000
    }
}

See the Configuring i3bar for details.

i3bar alternatives

Some users may prefer panels such as those provided by conventional Desktop Environments. This can be achieved within i3 by launching the panel application of choice during startup.

For the XFCE panel[broken link: invalid section], add the following line anywhere in ~/.config/i3/config:

exec --no-startup-id xfce4-panel --disable-wm-check

i3bar can be disabled by commenting the bar{ } section of ~/.config/i3/config, or defining a keybind to toggle the bar:

~/.config/i3/config
# bar toggle, hide or show 
bindsym $mod+m bar mode toggle

i3status

Copy over the default configuration files to the home directory:

$ cp /etc/i3status.conf ~/.config/i3status/config

Not all plugins are defined in the default configuration and some configuration values may be invalid for your system, so the need to be updated accordingly. See man i3status for details.

i3status replacements

https://github.com/brndnmtthws/conky || conky
  • i3blocks — Extensible via shell scripts. It can handle click events, interrupts, and defining of refresh intervals on a per-block basis.
https://github.com/vivien/i3blocks || i3blocksAUR
  • i3pystatus — Extensible Python 3 status bar with many plugins and configuration options by default.
https://github.com/enkore/i3pystatus i3pystatus || i3pystatus-gitAUR
  • i3situation — Another Python 3 status bar generator.
https://github.com/HarveyHunt/i3situation || i3situation-gitAUR
  • j4status — Provides a statusline, configurable via plugins, and written in C. Extra plugins are provided by j4status-plugins-gitAUR.
http://j4status.j4tools.org/ || j4status-gitAUR
  • goi3bar — i3status replacement written in Go. Configuration-file driven with several plugins, concurrency options, and rich plugin support.
https://github.com/denbeigh2000/goi3bar/ || goi3bar-gitAUR
  • goblocks — Fast, lightweight i3status replacement written in Go.
https://github.com/davidscholberg/goblocks || goblocksAUR
  • bumblebee-status — Theme-able Python status bar generator.
https://github.com/tobi-wan-kenobi/bumblebee-status || not packaged? search in AUR
  • ty3status — i3status replacement written in Typescript. Built with first class support for javascript blocks.
https://github.com/mrkmg/ty3status || ty3status-gitAUR

i3status wrappers

  • i3cat — A go based wrapper which can concatenate inputs from multiple external sources. It can handle click events and forwarding user specified signals to its subprocesses.
http://vincent-petithory.github.io/i3cat/ || i3cat-gitAUR
  • py3status — An extensible i3status wrapper written in Python.
https://github.com/ultrabug/py3status || py3statusAUR

Iconic fonts in the status bar

i3bar can be patched for XBM icon support, but you can use iconic font sets instead.

  • ttf-font-awesome — Scalable vector icons that can be customized with CSS. A cheatsheet shows the Unicode point for each glyph.
http://fortawesome.github.io/Font-Awesome/ || ttf-font-awesomeAUR
  • ttf-font-icons — Non-overlapping and consistently sized mix of Awesome and Ionicons. This also avoids minor overlapping between DejaVu Sans and Awesome.
http://kageurufu.net/icons.pdf || ttf-font-iconsAUR.

To combine fonts, define a font fallback sequence in your configuration file, separating fonts with , like so:

~/.config/i3/config
bar {
  ...
  font pango:DejaVu Sans Mono, Icons 8
  ...
}

In accordance with pango syntax, font size is specified only once, at the end of the comma-separated list of font families. Setting a size for each font would cause all but the last font to be ignored.

Add icons to the format strings in ~/.config/i3status/config using the unicode numbers given in the cheatsheets linked above. The input method will vary between text editors. For instance, to insert the "heart" icon (unicode number f004):

Merge-arrows-2.pngThis article or section is a candidate for merging with Internationalization.Merge-arrows-2.png

Notes: Should be described in one place; see also ArchWiki:Requests#Input methods. (Discuss in Talk:I3#)
  • in various gui text editors (e.g. gedit, Leafpad) and terminals (e.g. GNOME Terminal, xfce4-terminal): ctrl+shift+u, f004, Enter
  • in Emacs: ctrl+x, 8, Enter, f004, Enter
  • in Vim (while in insert mode): Ctrl+v, uf004
  • in urxvt: while holding Ctrl+Shift, type f004

Terminal emulator

By default when pressing $mod+Return it launches the i3-sensible-terminal which is a script that invokes a terminal. See man i3-sensible-terminal for the order terminals are invoked in.

To instead launch a terminal of choice, modify this line in ~/.config/i3/config:

bindsym $mod+Return exec i3-sensible-terminal

Alternatively, set the $TERMINAL environment variable.

Tips and tricks

Advanced window navigation

See i3 window Navigation Tips.

Jump to open window

  • quickswitch-i3 — Python utility to quickly change to and locate windows in i3
https://github.com/proxypoke/quickswitch-for-i3 || quickswitch-i3AUR
  • i3-wm-scripts — search for and jump to windows with particular names matching regexp
https://github.com/yiuin/i3-wm-scripts ||
  • winmenupy — Launches dmenu with a list of clients, sorted after workspaces. Selecting a client jumps to that window.
https://github.com/ziberna/i3-py/blob/master/examples/winmenu.py ||
  • rofi — Search and jump to open and scratchpad window
https://davedavenport.github.io/rofi/ || rofi

Jump to urgent window

Add to .i3/config: [1]

bindsym $mod+x [urgent=latest] focus

Save and restore the window layout

From version 4.8, and onward i3 can save and restore workspace layouts. To do this, the following packages are needed: perl-anyevent-i3 and perl-json-xs from the official repositories.

Note: This section only provides quick tutorial on how to save the current window layout of a single workspace and how to restore it for later use. Refer to the official documentation for more details

Save the current window layout of a single workspace

To save the current window layout, follow these steps:

  1. First, execute various commands to open windows in a preferred workspace and resize them if needed. Make sure to write down each executed command for each window.
  2. Now, in a new workspace, open a terminal and run the following:
    i3-save-tree --workspace N > ~/.i3/workspace_N.json
    where N is the number of the preferred workspace. This will save the current layout of workspace N to the file ~/.i3/workspace_N.json.
  3. The newly created file needs to be edited, however this may be done with the following commands:
    tail -n +2 ~/.i3/workspace_N.json | fgrep -v '// splitv' | sed 's|//||g' > ~/.i3/workspace_N.json

Restore the window layout of the workspace

There are two ways to restore the layout of the workspace: by writing a script, or by editing ~/.i3/config to automatically load the layout. In this section only the first case will be considered, refer to the official documentation for the second case.

To restore the saved layout in the previous section, write a file named load_layout.sh with the following contents:

  • The starting lines:
~/load_layout.sh
#!/bin/bash
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"

where M is the number of the workspace in which you would like to load the previously saved layout and N is the number of workspace saved in the previous section.

  • And the commands used in the previous section to get the preferred windows, but enclosed in parentheses and with an ampersand appended before the last parentheses.

For example, if the saved layout contained three uxterm windows:

~/load_layout.sh
#!/bin/bash

# First we append the saved layout of worspace N to workspace M
i3-msg "workspace M; append_layout ~/.i3/workspace_N.json"

# And finally we fill the containers with the programs they had
(uxterm &)
(uxterm &)
(uxterm &)

Then set the file as executable:

chmod u+x ~/load_layout.sh

And finally, the layout of worskpace N can be loaded onto to workspace M by running:

~/load_layout.sh
Tip: Adding bindsym $mod+g exec ~/load_layout.sh to ~/.i3/config and restarting i3 will bind Mod+g to run the above script.
Note: If the above script does not work properly, refer to the official documentation. The swallows sections of ~/.i3/workspace_N.json needs to be manually edited.

Scratchpad containers

By default, scratchpads only contain a single window. However, containers can also be made a scratchpad.

Create a new container (for example, Mod+Enter), split it (Mod+v) and create another container. Focus the parent (Mod+a), split in the opposite direction (Mod+h), and create again.

Focus the first container (with focus parent as needed), make the window floating (Mod+Shift+Space), and move it to the scratchpad (Mod+Shift+-). You can now split containers to preference.

Note: Containers cannot be resized individually in floating windows. Resize the containers before making windows floating.
Tip: When only using terminal applications, consider a multiplexer such as tmux instead.

See also [2] for multiple scratchpads.

Screensaver and power management

With Power management#xss-lock you can register a screenlocker for your i3 session. The -time option locks the screen after a given time period.

xautolock -time 10 -locker "i3lock -i 'background_image.png'" &

A systemd service file can be used to lock the screen before the system is being sent to sleep or hibernation state. See Power management#Suspend/resume service files. Note that i3lock requires the type of the service to be forking.

See also DPMS.

Shutdown, reboot, lock screen

Key combinations for shutdown, reboot and screenlock can be added to ~/.config/i3/config. The below example assumes you have polkit installed to allow unprivileged users to run power management commands.

set $Locker i3lock && sleep 1

set $mode_system System (l) lock, (e) logout, (s) suspend, (h) hibernate, (r) reboot, (Shift+s) shutdown
mode "$mode_system" {
    bindsym l exec --no-startup-id $Locker, mode "default"
    bindsym e exec --no-startup-id i3-msg exit, mode "default"
    bindsym s exec --no-startup-id $Locker && systemctl suspend, mode "default"
    bindsym h exec --no-startup-id $Locker && systemctl hibernate, mode "default"
    bindsym r exec --no-startup-id systemctl reboot, mode "default"
    bindsym Shift+s exec --no-startup-id systemctl poweroff -i, mode "default"  

    # back to normal: Enter or Escape
    bindsym Return mode "default"
    bindsym Escape mode "default"
}

bindsym $mod+Pause mode "$mode_system"

Once completed, you will be presented with a prompt whenever you press $mod+pause. For more complex behaviour, use a separate script, and refer to it in the mode. [3]

Note:
  • sleep 1 adds a small delay to prevent possible race conditions with suspend [4]
  • The -i argument for systemctl poweroff causes a shutdown even if other users are logged-in (this requires polkit), or when logind (wrongly) assumes so. [5]

For a list of alternative screen lockers, see List of applications/Security#Screen lockers.

External displays manual management

Thanks to xrandr there are many ways to easily manage systems displays. The below example integrates it in the i3 config file, and behave as the Power Management section above.

Here a laptop with both VGA and HDMI outputs will use a menu selection to switch them On/Off:

## Manual management of external displays
# Set the shortcuts and what they do
set $mode_display Ext Screen (v) VGA ON, (h) HDMI ON, (x) VGA OFF, (y) HDMI OFF
mode "$mode_display" {
    bindsym v exec --no-startup-id xrandr --output VGA1 --auto --right-of LVDS1, mode "default"
    bindsym h exec --no-startup-id xrandr --output HDMI1 --auto --right-of LVDS1, mode "default"
    bindsym x exec --no-startup-id xrandr --output VGA1 --auto --off, mode "default"
    bindsym y exec --no-startup-id xrandr --output HDMI1 --auto --off, mode "default"

    # back to normal: Enter or Escape
    bindsym Return mode "default"
    bindsym Escape mode "default"
}
# Declare here the shortcut to bring the display selection menu
bindsym $mod+x mode "$mode_display"

Any window that is still open in a switched Off display will automatically come back to the remaining active display.

The simplest way to determine names of your devices is to plug the device you wish to use and run:

$ xrandr --query

which will output the available, recognized devices and their in-system names to set your config file appropriately.

Refer to the xrandr page or man page for the complete list of available options, the i3 userguide and/or the i3 FAQ on reddit for more info.

Tabbed or stacked web-browsing

Some web-browsers intentionally do not implement tabs, since managing tabs is considered to be the task of the window manager, not the task of the browser.

To let i3 manage your tab-less web-browser, in this example for uzbl, add the following line to your ~/.config/i3/config

for_window [class="Uzbl-core"] focus child, layout stacking, focus

This is for stacked web browsing, meaning that the windows will be shown vertically. The advantage over tabbed browsing is that the window-titles are fully visible, even if a lot of browser windows are open.

If you prefer tabbed browsing, with windows in horizontal direction ('tabs'), use

for_window [class="Uzbl-core"] focus child, layout tabbed, focus

Workspace variables

As workspaces are defined multiple times in i3, assigning workspace variables can be helpful. For example:

set $WS1 term
set $WS2 web
set $WS3 misc
set $WS4 media
set $WS5 code

Then replace workspace names with their matching variables:

bindsym $mod+1          workspace $WS1
...
bindsym $mod+Shift+1    move container to workspace $WS1

See Changing named workspaces for more information.

Correct handling of floating dialogs

While dialogs should open in floating mode by default [6], many still open in tiling mode. To change this behaviour, check the dialog's WM_WINDOW_ROLE with xorg-xprop and add the correct rules to ~/.i3/config (using pcre syntax):

for_window [window_role="pop-up"] floating enable
for_window [window_role="task_dialog"] floating enable

You can also use title rules and regular expressions:

for_window [title="Preferences$"] floating enable

or WM_CLASS:

for_window [class="(?i)mplayer"] floating enable

Network Download/Upload speed on statusbar

You might adapt this upstream script. For that,

  • rename both network cards according to your system (use ip addr)
  • find them on /sys/devices then replace them appropriately:
$ find /sys/devices -name network_interface
Tip: Use /sys/class/net/interface/statistics/ to not depend on PCI location.

Now, just save the script in a suitable place (for example ~/.config/i3) and point your status program to it.

Patches

Merge-arrows-2.pngThis article or section is a candidate for merging with #Installation.Merge-arrows-2.png

Notes: One package does not warrant a separate section (Discuss in Talk:I3#)

Packages with patches not merged upstream are available in the AUR:

  • i3-wm-iconpatch — Titlebar icon support
https://github.com/ashinkarov/i3-extras || i3-wm-iconpatchAUR

Troubleshooting

General

In many cases, bugs are fixed in the development versions i3-gitAUR and i3status-gitAUR, and upstream will ask to reproduce any errors with this version. [7] See also Debug - Getting Traces#General.

Buttons in the i3 message bar do not work

Buttons such as "Edit config" in i3-nagbar call i3-sensible-terminal, so make sure your Terminal emulator is recognized by i3.

Faulty line wraps in tiled terminals

i3 v4.3 and higher ignore size increment hints for tiled windows [8]. This may cause terminals to wrap lines prematurely, amongst other issues. As a workaround, make the offending window floating, before tiling it again.

Mouse cursor remains in waiting mode

When starting a script or application which does not support startup notifications, the mouse cursor will remain in busy/watch/clock mode for 60 seconds.

To solve this for a particlar application, use the --no-startup-id parameter, for example:

exec --no-startup-id ~/script
bindsym $mod+d exec --no-startup-id dmenu_run

To disable this animation globally, see Cursor themes#Create links to missing cursors.

Unresponsive key bindings

Some tools such as scrot may not work when used with a regular key binding (executed after key press). In those cases, execute commands after key release with the --release argument [9]:

bindsym --release Print exec --no-startup-id scrot
bindsym --release Shift+Print exec --no-startup-id scrot -s

Tearing

i3 does not properly implement double buffering hence tearing or flickering may occur. To prevent this, install and configure compton. [10]

Tray icons not visible

The tray_output primary directive may require setting a primary output with xrandr, specifying the output explicitly or simply removing this directive. [11] See Xrandr for details. The default configuration created by i3-config-wizard no longer adds this directive to the configuration from i3 4.12.

See also

Arch Linux Forums

Screencasts