i3 manual

i3 is a lightweight tiling window manager focused on speed and keyboard control. Inspired by wmii, it targets developers. On first login, a default config is offered; accepting it gives sensible keybindings, workspace layout, and a i3bar. Users can later tweak settings, add autostart programs, tools like i3blocks, Rofi, and picom.

What is i3?

i3 is a dynamic tiling window manager designed for X11 that emphasizes keyboard-driven workflow and minimal resource usage. It was created as a lightweight alternative to full desktop environments, offering a clean, efficient interface for power users who prefer to keep their focus on terminal commands and text editors. The core philosophy of i3 is to provide a predictable, deterministic layout: windows are automatically tiled into non-overlapping regions, and the user can navigate, resize, and move them using a concise set of keybindings. This approach eliminates the need for mouse interactions and reduces the cognitive load associated with managing floating windows.

At its heart, i3 implements a flexible configuration system that is entirely text-based. The configuration file, typically located at ~/.config/i3/config, allows users to define workspaces, assign keybindings, and customize the appearance of the status bar (i3bar). The configuration syntax is intentionally simple, with comments and whitespace ignored, making it approachable for newcomers while still powerful enough for advanced users to script complex behaviors. For example, a user can bind a single key to launch a terminal, split the current workspace vertically, or switch to a different workspace, all within a few lines of configuration.

i3’s design is heavily influenced by the wmii window manager, but it introduces several enhancements such as support for multiple monitors, dynamic workspace creation, and integration with external status bars like i3blocks. It also supports a range of compositors, most notably picom, to add transparency, shadows, and animations without compromising performance. Because i3 is a window manager rather than a full desktop environment, it relies on external programs for features like application launching, desktop notifications, and system tray icons. Commonly used tools in the i3 ecosystem include Rofi for application launching, dmenu for quick command execution, and greenclip for clipboard management.

Installation of i3 is straightforward on most Linux distributions. On Debian-based systems, a single command such as sudo apt install i3 will pull in the core package, while on Arch Linux the equivalent is sudo pacman -S i3. After installation, the first login prompts the user to select a session; choosing i3 will start the window manager with a default configuration. Users are encouraged to accept the default config on first use, as it provides a solid foundation that can be incrementally customized. From there, the community offers a wealth of resources—official documentation, forums, and tutorials—to help users tailor i3 to their specific workflows.

Target Users and Philosophy

i3 is tailored for users who prioritize speed, keyboard control, and a minimalistic interface. Its design philosophy centers on deterministic tiling, predictable layouts, and a lightweight footprint that keeps system resources free for applications. The window manager is ideal for developers, power users, and those who spend most of their time in terminal-based workflows. By eliminating the need for mouse interactions, i3 allows users to focus on code, scripts, and command-line tools without the distraction of floating windows.

At the core of i3’s philosophy is the principle of “do one thing well.” The manager handles window tiling, workspace navigation, and status bar integration, while delegating other tasks—such as application launching, notifications, and desktop integration—to external utilities. This modular approach gives users the freedom to assemble a custom environment that fits their exact needs. For instance, Rofi can replace dmenu for application launching, picom can add transparency, and greenclip can manage the clipboard, all while i3 remains the central orchestrator.

i3’s target audience includes those who value a highly configurable setup, appreciate the ability to script window behavior, and seek a distraction-free workspace. The learning curve is steep for newcomers accustomed to floating window managers, but the payoff is a streamlined, keyboard-driven workflow that can dramatically increase productivity once mastered. Community resources, such as the official documentation, forums, and tutorials, help users navigate this learning curve and share custom configurations.

Because i3 is open source, the community continuously contributes patches, scripts, and configuration examples that extend its capabilities. Users can share their setups via GitHub or personal blogs, fostering a collaborative ecosystem where tweaks and improvements are rapidly disseminated. This openness ensures that i3 remains adaptable to new technologies, such as Wayland compatibility layers, while staying true to its core principles of simplicity and efficiency. Keep it simple!!!.

Key Features and Benefits

i3 offers a deterministic tiling layout that automatically arranges windows in a grid, eliminating gaps and maximizing screen real estate. The manager supports multiple workspaces, each with independent window arrangements, and provides keyboard shortcuts for moving, resizing, and swapping windows. Custom keybindings are defined in a plain text configuration file, allowing users to tailor the interface to their workflow. The i3bar, a lightweight status bar, can be extended with i3blocks to display system metrics, battery status, and network activity. Integration with external tools such as Rofi for application launching, dmenu for quick commands, and picom for transparency and compositing enhances the user experience without adding overhead. i3’s minimalistic design keeps the X server load low, resulting in snappy performance even on older hardware. The window manager’s open-source nature encourages community contributions, leading to frequent updates and a wealth of shared configurations. By focusing on keyboard control, i3 reduces mouse usage, allowing power users to navigate, edit, and manage applications more efficiently. The modular architecture lets users add or remove features as needed, keeping the environment lean and responsive. Overall, i3 delivers a fast, customizable, and distraction‑free workspace that appeals to developers, sysadmins, and anyone who values productivity and control. By leveraging external tools like Rofi for launching applications, i3blocks for a status bar, and picom for transparency, users can create a personalized veryenvironment that scales from a minimal setup to a desktop

Installation Overview

Installing i3 on a Linux distribution is straightforward. On Debian‑based systems, run sudo apt update && sudo apt install i3 to pull the latest package from the official repositories. For Arch Linux, use sudo pacman -S i3. If you prefer a minimal install, add i3-wm and optional i3status for a basic status bar. Once the package is installed, log out of your current session. At the login screen, choose the i3 session from the session selector – often represented by a gear icon or a drop‑down menu. The first time you start i3, the manager will prompt you to generate a default configuration file. Accepting the default creates ~/.config/i3/config, which contains example keybindings, workspace definitions, and i3bar settings. You can later edit this file to tailor the environment to your workflow. For users who want to integrate additional tools, installing i3blocks (e.g., sudo apt install i3blocks) provides a modular status bar, while rofi (sudo apt install rofi) offers a versatile application launcher. If you wish to add transparency and shadows, install picom (sudo apt install picom) and enable it in the i3 config with exec picom -b. Finally, reboot or restart your session to apply all changes. The i3 community offers extensive documentation and pre‑configured dotfiles, making it easy to jumpstart a productive tiling workflow.

After installing i3, add a compositor like picom for transparency: exec picom -b in your config. Install i3blocks for a status bar: exec i3blocks. Use rofi as a launcher: exec rofi These tools turn i3 in light desk now

Configuration Essentials

i3’s configuration resides in ~/.config/i3/config. It defines keybindings, workspaces, and startup commands. Use the default file as a template, then edit with a text editor. The config supports comments, variables, and exec directives for autostarting tools like i3bar, i3blocks, and picom. config.

Creating and Editing config file

When you first start i3, it will ask whether you want to generate a default configuration file. Accepting it creates a file at ~/.config/i3/config that contains a minimal set of keybindings, workspace definitions, and an example i3bar command. You can edit this file with any text editor, but it is recommended to use a plain‑text editor that preserves line endings and does not add hidden formatting.

To edit, open the file in your preferred editor, for example:

• nano ~/.config/i3/config
• vim ~/.config/i3/config
• gedit ~/.config/i3/config

Key elements of the configuration include:

• set $mod Mod4 – defines the modifier key (usually the Super/Windows key).
• bindsym $mod+Return exec i3-sensible-terminal – launches a terminal.
• bindsym $mod+Shift+q kill – closes the focused window.
• workspace 1: dev – names a workspace.

After making changes, reload the configuration with $mod+Shift+r or restart i3 entirely. The configuration file supports comments (lines starting with #) and variable substitution. For advanced users, you can include other files with include directives, or use exec_always to run programs on startup.

It is also possible to use exec_always --no-startup-id to prevent duplicate processes when reloading. Remember that the exec command runs once, while exec_always runs each time the configuration is reloaded. This distinction is crucial for services that should persist across sessions, such as a compositor or a status bar. Additionally, you can define custom commands and bind them to key combinations, enabling quick access to scripts or utilities you frequently use.

However, editing text file, allowing you to version‑control your settings and share them across machines. Remember to back up your config before making changes, as a corrupted file can prevent i3 from starting correctly!

Workspaces and Window Management

Workspaces in i3 are logical containers that hold windows. They are defined in the config file using the workspace keyword, followed by a number or name. For example, workspace 1: dev creates a workspace named “dev” on workspace 1. Users can switch between workspaces with $mod+1 to $mod+9, or use $mod+Shift+1 to move the focused window to that workspace. Workspaces can be renamed or reordered by editing the config file, and the workspace_layout option controls whether windows are tiled, floating, or split vertically. Window management in i3 is primarily tiling, meaning windows automatically occupy available screen space without overlapping. The default layout splits the screen into master and stack areas. The master area holds the primary window, while the stack contains additional windows. Users can resize windows with $mod+Ctrl+arrow or $mod+Shift+arrow to adjust the master size or move windows between master and stack. Floating windows are enabled with bindsym $mod+Shift+Space floating toggle, allowing temporary free‑form placement. The focus_follows_mouse option can be set to true to change focus when the mouse moves over a window. i3 supports dynamic workspace creation: new apps automatically can be assigned to a workspace that does not yet exist, and i3 will create it on demand. The workspace_auto_back_and_forth setting remembers the last workspace, enabling quick toggling between two recently used workspaces. Additionally, workspace_switch_back_and_forth allows cycling through used workspaces. !!

Keybindings and Customization

i3’s power lies in its keyboard‑centric design. The configuration file defines the $mod key (usually Alt or Super) and then maps combinations to actions. Common bindings include $mod+Enter to launch a terminal, $mod+Shift+q to close a window, and $mod+Shift+r to reload the config. Window navigation uses $mod+arrow to move focus, $mod+Shift+arrow to resize, and $mod+Shift+Space to toggle floating; Workspaces are accessed with $mod+1 to $mod+9, while $mod+Shift+1 moves the focused window to that workspace. Customization is achieved by editing the config file: you can change the $mod key, add new commands, or create custom keybindings that launch scripts or applications. For example, bindsym $mod+f exec firefox starts Firefox with a single key press. The exec_always directive runs a command at startup, useful for setting up environment variables or launching background services. i3 also supports assign rules to automatically place specific applications into designated workspaces, e.g., assign [class="Gimp"] 2 sends GIMP to workspace 2. Advanced users can employ the exec --no-startup-id option to run commands without creating a new window. The set command allows defining variables for reuse throughout the config. For instance, set $term alacritty then bindsym $mod+Return exec $term keeps the config DRY. i3’s keybinding system is highly flexible, enabling users to tailor the environment to their workflow, whether they prefer minimalism or a feature‑rich setup. Users can also bind mouse events, such as $mod+button1 to drag windows, or $mod+button3 to resize them. The config supports conditional statements, allowing different keybindings for different desktop environments or window classes. By leveraging the i3-msg command, scripts can query the current layout or send commands dynamically, enabling complex workflows like automatically arranging terminals in a grid when a project is opened. Additionally, i3’s built‑in scratchpad feature lets users hide windows temporarily with $mod+Shift+s and bring them back with $mod+Shift+s again, keeping the workspace clean. The ability to define custom workspace names and layouts per user makes i3 adaptable to both solo developers and collaborative teams. Furthermore, the i3 config supports environment variable expansion, so you can use $HOME or $PATH within commands. The config file is plain text, making version control straightforward; many users keep it in a Git repository to track changes. When editing, running i3-msg reload immediately applies changes without restarting the session. For debugging, the i3-msg -t get_tree command outputs the current window tree in JSON, which can be parsed by scripts to automate window placement. Finally, community‑maintained snippets and templates are available online, allowing newcomers to start with a proven setup and then tweak it to their liking. All these make i3 very customizable.

Autostart and i3bar

i3’s autostart mechanism is centered around the exec and exec_always directives in the configuration file. exec runs a command once when the session starts, while exec_always guarantees that the command is re‑executed whenever i3 reloads the configuration. This is useful for launching background services, setting environment variables, or starting desktop utilities such as picom for compositing, nm-applet for network management, or volumeicon for audio control. A typical autostart block might look like: exec_always --no-startup-id picom --config ~/.config/picom.conf. The --no-startup-id flag prevents the command from creating a window, keeping the desktop uncluttered. For applications that need to be restarted on every configuration reload, exec_always is the preferred choice; for one‑time startup tasks, exec suffices. The i3bar provides a lightweight status line that sits at the bottom of the screen by default. Its appearance and content are defined in the bar block of the configuration file. You can specify the status_command to run an external program that outputs JSON, such as i3status, i3blocks, or a custom script. The bar supports modules for workspace indicators, memory usage, battery status, date/time, and more. Customization options include font, background, foreground, separator_symbol, and separator_block_width. For example, font pango:DejaVu Sans Mono 10 sets a monospace font, while background #282c34 and foreground #c678dd create a dark theme. The status_command can be a chain of pipes: status_command i3status | i3blocks merges the output of both tools. To hide the bar, add hide_on_startup yes or use bar { mode hide }. The bar also supports click actions; you can bind a click on a workspace indicator to switch workspaces or launch a terminal. The configuration is parsed on every reload, so changes to the bar block take effect immediately. For advanced users, the bar { status_command i3status | i3blocks -c ~/.config/i3blocks/config } allows passing a custom configuration file to i3blocks, enabling per‑module settings. By combining autostart directives with a well‑configured i3bar, users can create a desktop that starts all necessary services and smoothly displays real‑time system information without the overhead of a full desktop environment. Additionally, you can replace i3status with the faster i3status-rust by setting status_command i3status-rust. The bar also supports per‑workspace color changes via workspace_bg and workspace_fg directives, allowing you to highlight the active workspace with a distinct hue. For users who prefer a minimalist look, the bar { status_command echo '' } can be used to display only the workspace icons. The bar’s modular design allows quick tweaks for ease and it. Finally, remember that any change to the bar configuration requires a reload; running i3-msg reload or pressing $mod+Shift+r applies the new settings instantly.

Enhancements and Workflow Tips

Use i3blocks to create custom status modules, Rofi for quick application launch, and picom for transparency. Bind keys to switch workspaces, toggle fullscreen, and launch terminals. Leverage scratchpads for temporary windows and use exec_always to keep background services running. Enjoy! 🙂

i3blocks for Status Bar

i3blocks is a modular status line generator that plugs into i3bar, providing real‑time system information without the overhead of a full desktop environment. It is written in C and can be extended with arbitrary executables, making it highly customizable. A typical i3blocks configuration file (~/.config/i3blocks/config) lists blocks in the order they should appear. Each block defines a command to run, an update interval, and optional formatting. For example:

cpu
 command /usr/bin/i3blocks-cpu
 interval 5
 label CPU
 color #f8f8f2
memory
 command /usr/bin/i3blocks-mem
 interval 10
 label MEM
 color #f8f8f2
time
 command date '+%H:%M'
 interval 60
 color #f8f8f2

Blocks can also be interactive. By setting click_command, a mouse click on the block can trigger a script, such as opening a terminal or toggling a network manager. The signal field allows external programs to force a block refresh. i3blocks supports color schemes, icons (via Font Awesome or Nerd Fonts), and even per‑block background colors. To integrate i3blocks with i3bar, add the following line to ~/.config/i3/config:

bar {
 status_command i3blocks
}

After editing the config, restart i3 (Mod+Shift+r) to see the new status bar. Advanced users can write custom scripts in any language, use environment variables, or parse JSON output. The community maintains a repository of ready‑made blocks for battery, network, volume, and more. By combining i3blocks with other tools like Rofi and picom, users create a lightweight, keyboard‑centric workflow that remains highly informative and responsive.

Users can also define custom signal handlers, enabling dynamic updates when system events occur. For instance, a script can listen for battery status changes and trigger a visual alert. The modular nature of i3blocks means you can drop in new blocks without touching the core configuration, keeping the status bar lean and fast.

Additionally, i3blocks can be configured to display system load averages, memory usage, or even custom scripts that query external APIs. By leveraging environment variables, you can tailor the appearance of each block, such as changing colors when a threshold is exceeded. The modular architecture allows you to keep the status bar lightweight while still providing rich information tailored to your workflow.!!

Rofi Launcher and Dmenu

Rofi and dmenu are lightweight launchers that integrate with i3. Rofi offers a modal interface where users type a command or window name and instantly filter results. It supports modes: run, window, ssh, dmenu, and custom scripts. By binding Mod+Alt+R to rofi -show run in the i3 config, users launch any executable without leaving the keyboard.

Dmenu, originally part of the suckless tools, follows a similar philosophy but is more minimal. It reads a list of options from stdin and displays a prompt at the top of the screen. A typical keybinding is Mod+Shift+Enter mapped to dmenu_run. While rofi has a richer UI, dmenu remains popular for its speed and low resource footprint.

Both launchers can be extended with custom scripts. For example, a rofi-theme file can change colors, fonts, and window placement. Dmenu can be wrapped in a shell script to provide a fuzzy search over bookmarks or recent documents. Users often combine rofi with the rofi-calc plugin for quick calculations or rofi-screenshot for screen captures. Its modular design lets developers write plugins in Python or Bash, integration with version and notifications!!

In addition to launching applications, rofi can manage windows. The rofi -show window command lists all open windows, allowing users to switch or move them between workspaces. Dmenu can also be used to select a workspace or toggle a compositor. By scripting these actions, users create a highly efficient workflow that stays within the i3 philosophy of keyboard‑centric control.

Installation is straightforward on most distributions: sudo apt install rofi dmenu or the equivalent package manager command. After installation, adding the keybindings to the i3 config file and restarting i3 will activate the launchers. For advanced users, the rofi -config option allows loading a custom configuration file, while dmenu can be customized via environment variables such as DMENU_HEIGHT and DMENU_PROMPT.

Compositors and Transparency (picom)

Picom is a lightweight compositor that adds shadows, fading, and transparency to the i3 tiling environment. It replaces the older xcompmgr and provides a modern, GPU‑accelerated pipeline. After installing with sudo apt install picom, launch it with picom --config ~/.config/picom.conf or add it to the i3 autostart file. To enable transparency, edit ~/.config/picom.conf and set backend = "glx"; followed by opacity = 0.9; for all windows, or use opacity-rule = ["90:class_g = 'Firefox'"]; to target specific applications. Picom supports per‑window rules, allowing fine‑grained control. The opacity‑rule syntax uses regular expressions to match window classes, titles, or roles. For example, opacity-rule = [“90:class_g = ‘Gimp’; 80:class_g = ‘Terminal'”]; gives GIMP 90% opacity and terminals 80%. The shadow option can be toggled with shadow = true; and its color, radius, and opacity adjusted via shadow-radius, shadow-opacity, and shadow-offset-x/y. Enabling fading adds smooth transitions when windows appear or disappear. To integrate picom with i3’s workspace switching, add exec –no-startup-id picom –config ~/.config/picom.conf to the i3 config. Use exec –no-startup-id picom –config ~/.config/picom.conf & for background execution. If you prefer a toggle, bind a key to exec picom –config ~/.config/picom.conf –replace and another to killall picom. This allows quick enabling or disabling of compositing without restarting i3. Picom’s configuration file supports color schemes for shadows and borders. The shadow-color can be set to #00000000 with an alpha value, e.g., shadow-color = “#00000080” for 50% shadow opacity. The blur section enables Gaussian blur on backgrounds; set blur-method = “dual_kawase” and blur-strength = 5; for a subtle effect. Transparency can also be applied to the i3bar by editing ~/.config/i3/config and adding bar { status_command i3status; colors { background #00000000; } }.