i3 is a tiling window manager for X11 that organizes your screen like a dynamic grid of containers rather than overlapping windows. Instead of clicking to move and resize, you assign keys to split, switch, and resize, which keeps your focus on the content itself. This guide walks through installing, configuring, and optimizing i3 for a reliable, keyboard-driven workflow.
Installing i3 and verifying your environment
On Debian-based distributions, install the i3 package with your system package manager. On Arch and derivatives, the same package is available in the official repositories. If you run a display manager, enable it for your user so the session appears in the login screen. Before you log in, confirm that your hardware supports X11, since i3 does not yet handle Wayland natively. Once logged in, you should see a basic layout with a status bar at the top and a centered floating terminal window.
Understanding the i3 configuration file
The main configuration file lives at ~/.config/i3/config, and i3 will open it automatically on first start. Comments start with a #, and long commands can be split across lines using a backslash. Modifications take effect immediately after you reload i3, which you can do with the default Mod+Shift+R shortcut. Keep a backup of the file and test small changes, since a syntax error will prevent i3 from loading and may drop you into a fallback session.
Key bindings and modifier keys
The modifier, often called Mod or Super, is usually the Windows key, and it forms the base for every binding. You can create chains of commands by defining a prefix key, then combining it with a letter or symbol to launch an application, switch containers, or adjust layout. For example, Mod+Enter opens a terminal, Mod+J moves focus downward, and Mod+Shift+Q prompts you to exit i3 cleanly. Advanced users remap Mod to Caps Lock or assign bindings for workspaces, scratchpads, and floating rules.
Workspaces, containers, and layout basics
Workspaces act as virtual desktops, and you can jump between them with Mod+Number or Mod+Arrow. Containers split horizontally with Mod+H and vertically with Mod+V, creating a binary tree that divides screen space without gaps. You can switch focus with Mod+J and Mod+K, or move containers between splits with Mod+Shift+Arrow. When you float a window, it sits above the tiling grid, and you can pin certain apps to all workspaces for persistent toolbars and alerts.
Practical workflows for common tasks
Open a terminal with Mod+Enter, then split it to run a build process beside your editor. Assign frequent apps to key combinations so you can launch them in one stroke, and group related clients in scratchpads for quick popovers. Use marks to label containers, then jump back with Mod+Mark, which is invaluable when navigating deep trees. Combine i3 with status tools that report battery, network, and notifications, so your bar becomes a concise dashboard rather than a distraction.
Troubleshooting and refining your setup
If an application misbehaves, mark its window and inspect the tree to see how splits and floating rules interact. Logs in ~/.i3/i3.log capture configuration errors and runtime events, helping you trace a bad binding or startup command. Optimize startup applications with exec and exec_always, ensuring heavy clients do not block the bar from appearing. Periodically review your config to remove unused bindings, group commands into aliases, and keep the file readable with clear comments and consistent indentation.
