I3 User Manual

Getting Started with I3 Without Losing Your Mind

I3 is a tiling window manager for X11. It handles window layout through keyboard shortcuts rather than mouse dragging, and it splits your screen into nested frames where windows are placed automatically. The configuration lives in ~/.config/i3/config. That single file controls everything from keybindings to workspace behavior to status line output. When you install it, the default config is decent enough to get through, but it will not feel like anything you actually use after three days. I learned this because I spent about two weeks fighting with the default bindings before realizing I had been reading the wrong section of the manual backwards. The I3 User Manual is actually structured in a way that rewards reading the configuration reference before the keybinding list. Most people jump straight to the "How do I remap Alt+Tab?" question and then wonder why nothing responds after they edit the file.

I3 User Manual Structure and Where Things Actually Live

The official manual is hosted at i3wm.org/docs and broken into sections: installation, getting started, configuration reference, workspaces, containers, commands, and troubleshooting. The configuration reference is where you spend most of your time once you move past defaults. It documents every directive you can put in the config file, from bindsym and exec to gaps inner and floating_modifier. One thing the manual does not make obvious is that i3 reads the config file in a single pass when it starts. There is no hot reload for most directives unless you use i3-msg reload, and even then some things like changed workspace layouts on existing containers require a restart to take effect. I wasted an afternoon once thinking a gaps setting was ignored when in fact I had typed it inside a mode block by accident. The config parser silently accepted it because mode blocks accept most directives, but the gaps were scoped to that named mode and never applied to normal operation.

Configuration Basics That Actually Matter

Your config file is line-ordered. The first binding that matches a key combination wins. This matters more than the manual makes it sound because I3 does not merge overlapping bindings the way some desktop environments do. If you have a bindsym for $mod+f and later in the file another rule targets the same key under a different condition, only the first one fires. Put your general bindings near the top and your special-case overrides below them. I usually group mine as follows: modifier definitions first, then global bindsym entries, then workspace-specific rules, then mode blocks at the bottom. The floating_modifier directive is one of those things that seems minor until you discover it. It lets you hold a key and drag any tiling window into floating mode without manually toggling float per window. I set mine to Alt and have not touched mode floating since. The manual mentions it briefly in the commands section, which is why most people miss it entirely. Status bar configuration goes through i3status or i3bar. The default i3status.conf is functional but bare. I replaced it with a custom setup using script output for system info and kept the built-in blocks for network, volume, and date. The manual covers this in the status line section, but the examples there assume you want their exact output format. If you need custom JSON from a script, you just point the output directive at your executable and format the response however you like. I use a small Python script that pulls battery percentage and network signal strength into a single bar segment because the default blocks do not expose signal quality on Wi‑Fi.

Workspaces and Containers: What the Manual Gets Right and Wrong

I3 treats workspaces as named slots rather than virtual desktops in the macOS sense. You can jump between them with $mod+number, and you can move windows between them with $mod+shift+number. The auto_back_and_forth option switches between the two most recently used workspaces when you press the same number twice. Enable it if you toggle between two panes constantly. I have it on by default. Containers are the nested frames that hold your windows. I3 uses split layouts: horizontal, vertical, or tabbed. The manual explains how to create them with split h and split v, but it does not emphasize enough that split commands apply to the currently focused container, not the root workspace. If you are trying to reorganize a workspace and your splits are going the wrong direction, you are probably focused on a child container instead of the parent. Press $mod+Shift+C to close the focused container and start from the workspace level, or use $mod+Up/Down to change the split direction of the current container explicitly. Here is a counter-intuitive detail most beginners miss: when you enable gaps via gaps inner or gaps outer, the gap value applies per-container, not per-window. If you have a vertical container holding two horizontal containers, the inner gaps stack between the sub-containers in a way that can produce uneven spacing. I ran into this when I tried to set uniform 5px gaps across a complex multi-split layout and ended up with 10px seams between nested frames. The fix was to flatten the layout by merging containers with $mod+Shift+E until the structure was a single horizontal or vertical tree, then apply gaps once at the top level.

Common Pitfalls and Edge Cases

Application-specific floating rules are useful but fragile. If you define floating_enable for a class and that application reports a different WM_CLASS after an update, your rule silently stops working. I learned this the hard way when a browser update changed its class identifier from Firefox to something else, and all my floating rules for it vanished overnight. The workaround is to query the actual WM_CLASS with xprop and use the exact string, or target the instance field separately if the app varies it between windows. Another pitfall involves startup programs. Using exec in the config file runs programs once at session start. Using exec_always reruns the command every time i3 restarts, which is necessary for daemons like dunst or polybar. I confused the two initially and had polybar running two instances after every reload, which caused duplicate systray entries and confused mouse clicks. The manual distinguishes them in the configuration reference, but the difference only matters when something breaks. Fullscreen behavior in I3 is not the same as toggle fullscreen in a desktop environment. $mod+f toggles fullscreen for the focused window, but it does not hide the status bar or panel by default. If you want a true fullscreen experience for media or presentations, you need to configure a separate binding or use a script that temporarily hides the status bar via i3-msg commands. I add a $mod+Shift+f binding that runs a small shell script: it sends focus to the bar, hides it, toggles fullscreen on the target window, then refocuses. Reverse it on the second press.

Debugging When Things Break

i3 provides a built-in debugging log at ~/.config/i3/log. When your config changes have no effect or keys stop responding, run i3 --restart from a terminal or use $mod+Shift+c to enter command mode and type exec i3 --restart. The log file will show parse errors, unrecognized directives, and binding conflicts. I check it before asking anyone for help online because 90 percent of config issues leave a trace there. The command mode accessible via $mod+d is also useful for live testing. You can type i3 commands directly without editing the config file. This saves time when you are unsure whether a directive is valid. Type gaps inner 5 and hit Enter to see if it applies immediately. If it does, add it to your config. If it errors out, the log will tell you why. Dowloading the manual itself is not necessary since it is web-based, but you can clone the source repository from github.com/i3/i3 to get the markdown sources if you prefer offline reading or want to contribute corrections. The docs live in the doc folder and are generated into the website. Most updates to the manual come from community pull requests, so if you find a section that is outdated or misleading, submitting a fix is straightforward.

What I3 Still Gets Wrong

I3 does not support Wayland. If you are running a Wayland session, you need to look elsewhere. I3 also lacks built-in workspace renaming through the config directives alone. You have to use i3-msg to rename workspaces at runtime, and the manual does not highlight this limitation clearly. Multi-monitor setups work well but require careful setup of gaps_per_workspace and output-specific rules if you want different gap values per screen. The default behavior applies the same gaps to every output, which looks wrong if your monitors have different resolutions. For most users, I3 remains one of the most reliable tiling window managers available. The config file approach is explicit and debuggable. The learning curve is real but finite, and the manual covers the surface area adequately once you know where to look. Start with the getting started guide, move to the configuration reference for specifics, and keep the log path in your back pocket for when things go sideways.