Difference between revisions of "I3"

From ArchWiki
Jump to navigation Jump to search
(→‎i3bar alternatives: nowiki tags, add template:accuracy)
Line 300: Line 300:
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].
For a list of alternative screen lockers, see [[List of applications/Security#Screen lockers]].
* If you use {{AUR|xss-lock}}, call {{ic|xset s activate}} to start the locker.
* With {{Pkg|xautolock}} the command is {{ic|xautolock -locknow}}
=== Tabbed or stacked web-browsing ===
=== Tabbed or stacked web-browsing ===

Revision as of 01:00, 6 September 2014


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.


Install the i3 package group from the official repositories. 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 i3#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.


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

Nvidia binary drivers before version 302.17 need the --force-xinerama flag. A detailed explanation can be found at i3wm.org.

exec i3 --force-xinerama

If you have trouble mapping keys (e.g. ; as semicolon), use xorg-xev or see Extra keyboard keys.

$ xev | grep -A2 --line-buffered '^KeyRelease' | sed -n '/keycode /s/^.*keycode \([0-9]*\).* (.*, \(.*\)).*$/\1 \2/p'


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

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; it is a near-drop-in replacement for i3-dmenu-desktop, but much faster[1].


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.

See the i3 reference card and Using i3 for default keybindings.


Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: The User's guide explains basic use of containers, yet not sufficiently clear to allow for more advanced use cases. It also does not mention focus child as it does focus parent. (Discuss in Talk:I3#)

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.


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


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
  • 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


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:

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, add the following line anywhere in ~/.config/i3/config:

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

Alternatively if using startx, this can be done in your xinitrc:

xfce4-panel --disable-wm-check &

Tango-inaccurate.pngThe factual accuracy of this article or section is disputed.Tango-inaccurate.png

Reason: i3 is NETWM compliant, so workspace management from external panels should usally work. See also [1] (Discuss in Talk:I3#)
Note: Panel features that are specific to the Desktop Environment (e.g., widgets for managing workspaces/sessions) will most likely not work, though i3's functionality should remain unaffected.

i3bar can be disabled by commenting out the bar{ } section of ~/.config/i3/config.


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, see man 1 i3status for details.

Note: The example configuration file uses eth0 and wlan0 as interface names, see Network configuration#Device names if they do not match with your system. See man i3status for other possible mismatches, such as the battery path.

i3status replacements

http://conky.sourceforge.net/ || 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.
http://j4status.j4tools.org/ || j4status-gitAUR

i3status wrappers

  • h2status — Bash wrapper for i3status that allows custom json entries as input, and can handle click events as well as asynchronous updates of the status bar.
https://wiki.archlinux.org/index.php/H2status || h2statusAUR
  • 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.
https://www.dropbox.com/s/9iysh2i0gadi4ic/icons.pdf || ttf-font-iconsAUR.

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

bar {
  font pango:DejaVu Sans Mono, Icons 8

You have to first list the comma separated font families and then add only one size specification at the end of the string. Do not set a size for each family (even if the size is the same) and do not 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.

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: Not everyone uses vim (Discuss in Talk:I3#)

Finally, enter the iconic glyphs into the format strings in ~/.config/i3status/config. For this, use the unicode numbers given in the cheatsheets linked above. For example, if you're using vim while in insert mode you can type Ctrl+v, followed by the unicode hexadecimal number for the glyph.

In urxvt, hold down Ctrl+Shift, followed by the desired Unicode point.

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, locally define the $TERMINAL variable:

$ export TERMINAL=yourterminal

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 ||

Jump to urgent window

Add to .i3/config: [2]

bindsym $mod+x [urgent=latest] focus

Save the current session

From version 4.8, i3 can save and restore workspace layouts. See layout saving in i3 for details.

To save and restart full sessions, install i3session-gitAUR from the AUR.

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 [3] for multiple scratchpads.

Screensaver and power management

You can use DPMS to blank your screen or to suspend/poweroff your monitor. Adding the following line to your ~/.config/i3/config will suspend your monitor after 10 minutes.

exec --no-startup-id xset dpms 600

With xss-lockAUR you can register a screenlocker for your i3 session. xss-lock subscribes to the systemd-events suspend, hibernate, lock-session, and unlock-session with appropriate actions (run locker and wait for user to unlock or kill locker). It also reacts to the X screensaver and runs or kills the locker in response to the x-server signals. Start xss-lock in your autostart like this:

xss-lock -- i3lock -i background_image &

Alternatively, use xautolock to lock the screen after a given time period:

xautolock -time 10 -locker i3lock &

See also #Shutdown.2C_reboot.2C_lock_screen.

Shutdown, reboot, lock screen

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 i3exit. Remember to make it executable with chmod +x and to place it somewhere in your $PATH. This script assumes that you have polkit installed to allow unprivileged users to run power management commands.

lock() {

case "$1" in
        i3-msg exit
        lock && systemctl suspend
        lock && systemctl hibernate
        systemctl reboot
        systemctl poweroff
        echo "Usage: $0 {lock|logout|suspend|hibernate|reboot|shutdown}"
        exit 2

exit 0

Now add the following lines to your ~/.config/i3/config Once completed you will be presented with a prompt whenever you press $mod+pause.

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 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"

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

  • If you use xss-lockAUR, call xset s activate to start the locker.
  • With xautolock the command is xautolock -locknow

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 [4]:

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.


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

  • i3bar-icons-git — Display XBM icons in i3bar
https://github.com/ashinkarov/i3-extras || i3bar-icons-gitAUR
  • i3-mouse-close — Middle-click close support
https://faq.i3wm.org/question/550/manipulating-windows-with-the-mouse || i3-mouse-closeAUR
  • i3-smart-border — Smart borders
https://github.com/ashinkarov/i3-extras || i3-smart-borderAUR
  • i3-wm-iconpatch — Titlebar icon support
https://github.com/ashinkarov/i3-extra || i3-wm-iconpatchAUR



Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: Official debugging instructions may not work as expected, so expand on this topic (Discuss in Talk:I3#)

In many cases, bugs are fixed in the development version i3-gitAUR (from the AUR) and upstream will ask to reproduce any errors with this version. [5]

Warning: Debugging symbols are removed in the AUR package. See Debug - Getting Traces#General before sending backtraces upstream.

Buttons in the i3 message bar do not work

Buttons such as "Edit config" in i3-msg 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 [6]. 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[7]:

bindsym --release Print exec --no-startup-id scrot '%Y-%m-%d$
bindsym --release Shift+Print exec --no-startup-id scrot '%Y$


i3 does not properly implement double buffering hence tearing or flickering may occur. In case of problems, try using a composite manager.

See also

Arch Linux Forums