From Gentoo Wiki
Jump to:navigation Jump to:search

i3 is a minimalist tiling window manager, completely written from scratch.

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
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)


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

savedconfig Use this to restore your config from /etc/portage/savedconfig ${CATEGORY}/${PN}. Make sure your USE flags allow for appropriate dependencies
xinerama Add support for querying multi-monitor screen geometry through the Xinerama API

Want to see .desktop apps also? Use i3-dmenu-desktop (wrapper for dmenu - dmenu needs to be installed), example config:

FILE ~/.config/i3/config
bindsym $mod+d exec i3-dmenu-desktop

With parameters to dmenu:

FILE ~/.config/i3/config
bindsym $mod+d exec i3-dmenu-desktop --dmenu 'dmenu -fn "Droid Sans Mono-35" -b -l 20'


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 bandwidth
pulseaudio Add sound server support via media-libs/libpulse (may be PulseAudio or PipeWire)


A more (relative to the more popular i3status) advanced, extensively-customizable status (for the i3bar config to use) is provided by i3blocks.

root #emerge --ask x11-misc/i3blocks


i3lock is an i3 compatible screen locker.

root #emerge --ask x11-misc/i3lock
Active context menus, like dmenu, effectively prevent the locking process to succeed[1].


x11-misc/polybar is an alternative to i3bar. Please review its own wiki page for details.


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.

Starting i3

It's recommended that Dbus is used for applications to work correctly.

Most users will probably want i3 started via the X server's ~/.xinitrc file, probably replacing the contents of any existing ~/.xinitrc with the following:

FILE ~/.xinitrc

# Option 1: launch with a dbus session (recommended)
exec dbus-launch --exit-with-session i3
# Option 2: launch without dbus
#exec i3

After this code has been added to a user's .xinitrc file, running startx will start i3.

When not using a login manager, security issues arise when relying on a screen lock program such as i3lock, as such programs only prevent access to the running X session. The tty where X was launched may still be accessible, and it would be possible to kill X to gainin access to a shell for the logged in user. To ensure that if X is terminated for any reason, the user will be logged out, make sure i3 is launched with the exec command:
user $exec startx

Default keybinding

Additional keybinding information can be found on upstream's website.


  • Spawn a new terminal: META+Enter
  • Kill the focused window: META+Shift+Q

bindsym $mod+Return exec i3-sensible-terminal
bindsym $mod+Shift+q kill

Moving around

  • Move the focus: META+Arrow_Key
  • Move the focused window: META+Shift+Arrow_Key
  • Alternative (vi like) way of moving the focus: META+J,K,L,;
  • Switch to workplace Num: META+Num
  • Set vertical split mode for the focused container: META+V
  • Set horizontal split mode for the focused container: META+H
  • Set the tabbed mode for the focused container: META+W
  • Set the stacking mode for the focused container META+S
  • Set the split mode for the focused container: META+E
# Change the focused window
bindsym $mod+Left focus left
bindsym $mod+Down focus down
# Move the focused window
bindsym $mod+Shift+Up move up
bindsym $mod+Shift+Right move right
# Define the workplaces
set $ws1 "1"
set $ws2 "2"
# Switch the workplace
bindsym $mod+1 workspace number $ws1
bindsym $mod+2 workspace number $ws2
# View management
bindsym $mod+h split h
bindsym $mod+v split v
bindsym $mod+s layout stacking
bindsym $mod+w layout tabbed
bindsym $mod+e layout toggle split

Moving windows

  • Toggle floating for focused window: META+Shift+Space
  • Move focused window: META+MOUSE1
  • Resize focused window: META+MOUSE2
  • Resize focused windows in tiled mode: META+R
  • Open focused window in fullscreen: META+F

Utilities keybinding

  • Open dmenu (or an alternative application launcher): META+D

Administrative keybinding

  • Exit i3: META+Shift+E
  • Restart i3: META+Shift+R

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 htop utility when Ctrl+Shift+Escape is pressed:

bindsym Ctrl+Shift+Escape exec htop

Set 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

Changing default terminal

Default terminal can be configured in /home/̩$USER/.config/i3/config by changing bindsym $mod+Return exec i3-sensible-terminal on terminal of your choice. Alternatively, you can set the TERMINAL environment variable.

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 (need media-sound/alsa-utils for amixer.)
bindsym XF86AudioRaiseVolume exec amixer -q set Master 10%+ unmute
bindsym XF86AudioLowerVolume exec amixer -q set Master 10%- unmute
bindsym XF86AudioMute exec amixer -q set Master toggle

# PulseAudio key bindings (need USE flag "pulseaudio", will pull in media-sound/pulseaudio automatically.)
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 (need media-sound/playerctl for playerctl.)
bindsym XF86AudioPlay exec playerctl play
bindsym XF86AudioPause exec playerctl pause
bindsym XF86AudioNext exec playerctl next
bindsym XF86AudioPrev exec playerctl previous
# Brightness key bindings (need x11-apps/xbacklight for xbacklight.)
bindsym XF86MonBrightnessUp exec xbacklight -inc 10
bindsym XF86MonBrightnessDown exec xbacklight -dec 10

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

Tips and tricks

Autostart on a specific workspace (display)

For example Firefox on workspace 2:

FILE ~/.config/i3/config
exec i3-msg 'workspace 2; exec firefox'

Setting a wallpaper

A wallpaper can be easily set using Feh. Example configuration line: exec --no-startup-id feh --bg-scale /path/to/wallpaper.

Transparent background

i3 do not provide compositing. Install x11-misc/xcompmgr to add window transparency and animation effects support for i3. Example configuration line: exec --no-startup-id xcompmgr

The Scratchpad (i3's solution to minimising windows)

The i3 wm has an invisible workspace called the Scratchpad workspace. Users can move windows to and from it to hide them from the main workspaces. The i3 commands move scratchpad and scratchpad show hide and show windows respectively. It may be useful to bind these to keys within your config:

FILE ~/.config/i3/config
# Make the currently focused window a scratchpad
bindsym $mod+minus move scratchpad

# Show the first scratchpad window
bindsym $mod+plus scratchpad show

Configuring gaps between tiled windows

The following lines remove the window decorations and add gaps between the windows. smart_gaps on will disable the gaps if only one window is present on a workspace.

Change the values for preference. This will put a 5px gap between all containers and the edge of the screen.

gaps inner sets the distance between adjacent containers. gaps outer sets the distance between containers and the edge of the screen. It is worth noting that the actual distance from the containers to the edge of the screen is the sum of the inner and outer values. The actual distance between adjacent containers is the inner value alone.

CODE Configuring gaps between tiled windows
for_window [class="^.*"] border pixel 0
gaps inner 5
gaps outer 0
smart_gaps on

Windows-like functions

Alt-TAB to cycle between workspaces

With the following configuration, use META+TAB to switch to next open workspace and META+SHIFT+TAB to switch to the previous one. META+` can be used to jump back to the last used workspace:

CODE Adding ALT + TAB Functionality
# enable Alt+Tab Functionality
bindsym $mod+Tab workspace next
bindsym $mod+Shift+Tab workspace prev

# jump to last used workspace
bindsym $mod+grave workspace back_and_forth

Lock the session

Lock the session when Mod+L is pressed.

Ignore empty password entries and set the background image to ~/Pictures/lockscreen.png.

bindsym $mod+l exec i3lock --ignore-empty-password -i ~/Pictures/lockscreen.png

Capture a portion of the screen to the clipboard

Take a screenshot with media-gfx/scrot when releasing the Mod+Shift+s key combination. The image will be saved to /tmp/snip.png.

The -f or --freeze flag freezes the screen and -s or --select flag enables cropping the screenshot to a selection.

Copy the selection to the clipboard using x11-misc/xclip.

FILE ~/.config/i3/configScreenshot with regional selection
bindsym --release $mod+Shift+s exec --no-startup-id scrot -s -f -o /tmp/snip.png && xclip -selection clipboard -t image/png -i /tmp/snip.png

To improve the quality of screenshots being taken an additional -q or --quality flag can be added to the scrot utility. The -q flag expects a numeric value between 1 and 100, where 1 is the worst and 100 is the best image quality.

Lock the session during sleep or hibernate

With x11-misc/xss-lock i3 can be instructed to activate the screen locker, e.g. x11-misc/i3lock during sleeping or hibernating.

exec --no-startup-id /usr/bin/xss-lock -- /usr/bin/i3lock -n -c 000000

Known issues

i3 softbricks if xrandr with scale is used

i3 softbricks if xrandr --scale 1.1x1.1 (or any scale above 1.1x1.1) is invoked.

Partially solved?, resolving on https://github.com/i3/i3/issues/3392

1. xrandr with --scale is still unable to work correctly (results in softbrick with GPU glitches if used) with multiple outputs. Temporary solution is to invoke xorg-server for each output, but it will make them independant from each other meaning that you can NOT drag windows through multiple outputs.

2. xrandr with --scale sometimes work and sometimes it doesn't...

Reported by Kreyren (talk) 14:47, 15 September 2018 (UTC)

Changing kill command on Alt+F4 does not affect terminal.

Changing /home/$USER/.config/i3/config section # kill focused windows on bindsym ALT+F4 kill does not affect terminal emulator -> unable to close terminal emulator.

If anyone knows the solution please share it. Kreyren (talk) 18:26, 8 September 2018 (UTC)


This section was created to help users diagnose their i3.

Error: status_command not found or is missing a library dependency (exit 127)

The default setting of status_command in the /home/$USER/.config/i3/config expects installed i3status. This error could be resolved by either emerging x11-misc/i3status or changing the status_command.

Error while emerging: fatal error: GENERATED_config_enums.h: No such file or directory

Check the value of MAKEOPTS environment variable. If the amount of make jobs is set to higher than -j1 – set it to -j1 value for the duration of compilation:

root #MAKEOPTS="-j1" emerge -a x11-wm/i3

To permanently use this configuration for emerging i3 – set up /etc/portage/package.env for i3.

See also

External resources