From Gentoo Wiki
Jump to: navigation, search

i3 is a minimalist window manager, focusing on keyboard commands to manipulate windows. By default all windows are in full-screen in order to best maximize the use of the screen and have less fiddling with positioning. Even with the doc USE flag enabled its installed size is less than 1.6 MB. It also uses less than 10 MB of RAM under normal operating conditions.


USE flags

USE flags for x11-wm/i3 An improved dynamic tiling window manager

doc Build and install the HTML documentation and regenerate the man pages local


The basic package is i3 itself

root #emerge --ask x11-wm/i3

Additional software


It is also assumed that dmenu will be emerged. Available USE flags include:

USE flags for x11-misc/dmenu a generic, highly customizable, and efficient menu for the X Window System

xinerama Add support for querying multi-monitor screen geometry through the Xinerama API global


i3status provides status information that can be used by i3bar which, by default, sits at the bottom of the screen. Available USE flags include:

USE flags for x11-misc/i3status generates a status bar for dzen2, xmobar or similar

filecaps Linux capabilities library is required for i3status to be able to read net bandwith local


A more (relative to the more popular i3status) advanced, extensively-customizable status (for the i3bar config to use) is provided by i3block. Available USE flags include:

USE flags for x11-misc/i3blocks highly flexible status line for the i3 window manager


If one wants screen-locking it is advisable to use i3lock. USE flags include:

USE flags for x11-misc/i3lock Simple screen locker


i3 can be extensively customized by editing its config. The main user config file for i3 can be either in ~/.config/i3/config or ~/.i3/config. By default when i3 is run for the first time a new config file is added to ~/.i3/config and a dialog asks what the modifier key should be set to. The default modifier key is Alt and a popular alternative is the Super (Windows) key (referred to as $mod4 in ~/.i3/config). A popular starting point for writing the config file is copying the system config file /etc/i3/config to one of the user config locations if one is not already generated.

Adding commands

In the user config file, adding a keyboard command is as simple as adding a line. For example, adding the following to the end of the config will open the gnome-system-monitor utility when Ctrl+Shift+Escape is pressed:

bindsym Ctrl+Shift+Escape exec gnome-system-monitor

You can also have it use the default key that all other commands use by using the built-in variable:

bindsym $mod+f exec firefox

You can also set you own variable names or override values of variables. It works by replacing text, like the c pre-processor, and has no concept other than strings.

set $someVarName SomeValue

Adding modes

You can also add in what is called a mode. An example is the resize mode for floating windows. This changes what keyboard commands are bound and will be able to run. This is useful if there is a large set of commands often run together, or that override the keys on the keyboard as in the example below which takes over the arrow keys and the vim-style movement keys.

CODE Resize mode taken from example config
mode "resize" {
        # These bindings trigger as soon as you enter the resize mode

        # Pressing left will shrink the window’s width.
        # Pressing right will grow the window’s width.
        # Pressing up will shrink the window’s height.
        # Pressing down will grow the window’s height.
        bindsym j resize shrink width 10 px or 10 ppt
        bindsym k resize grow height 10 px or 10 ppt
        bindsym l resize shrink height 10 px or 10 ppt
        bindsym semicolon resize grow width 10 px or 10 ppt

        # same bindings, but for the arrow keys
        bindsym Left resize shrink width 10 px or 10 ppt
        bindsym Down resize grow height 10 px or 10 ppt
        bindsym Up resize shrink height 10 px or 10 ppt
        bindsym Right resize grow width 10 px or 10 ppt

        # back to normal: Enter or Escape
        bindsym Return mode "default"
        bindsym Escape mode "default"
# A binding to change over into the resize mode
bindsym $mod+r mode "resize"
Always provide a binding inside of any mode that returns you to the default mode, or else you will be stuck in that mode. If you get stuck, you must restart X to reset i3 into default mode.

Enabling Multimedia keys

You can add Multimedia key bindings in your i3 config. Below are example of working Multimedia keys with i3wm.

CODE Enabling Multimedia keys
# Put this in your i3 config file
# Alsa key bindings
bindsym XF86AudioRaiseVolume exec amixer -q set Master 10%+ unmute
bindsym XF86AudioLowerVolume exec amixer -q set Master 10%- unmute
bindysm XF86AudioMute exec amixer -q set Master toggle

# PulseAudio key bindings
bindsym XF86AudioRaiseVolume exec amixer -D pulse sset Master 10%+ unmute
bindsym XF86AudioLowerVolume exec amixer -D pulse sset Master 10%- unmute
bindsym XF86AudioMute exec amixer -D pulse sset Master toggle

# Media player key bindings (you need playerctl for this to work.)
bindsym XF86AudioPlay exec playerctl play
bindsym XF86AudioPause exec playerctl pause
bindsym XF86AudioNext exec playerctl next
bindsym XF86AudioPrev exec playerctl previous
# Brightness key bindings
bindsym XF86MonBrightnessUp exec xbacklight -inc 10
bindsym XF86MonBrightnessDown exec xbacklight -dec 10

For a complete reference, visit the i3 official user guide.

External resources