When the desktop environment gets in the way
You spent three hours reading about keyboard-driven workflows. You want your windows to tile automatically, your terminal to stay open, and your mouse to gather dust. You install i3, log out, and select the session. The screen goes black. Or worse, it loads but nothing responds to your keyboard. You are not broken. The window manager is waiting for you to tell it how to behave.
How i3 actually manages your screen
i3 is a tiling window manager, not a desktop environment. It does not ship with a panel, a notification daemon, a power manager, or a file manager. It ships with a text file and a set of rules. When you launch a program, i3 reads its configuration, assigns it to a workspace, and tiles it next to whatever is already open. If the configuration file is missing or malformed, i3 falls back to hardcoded defaults that rarely match modern hardware or user expectations.
Think of i3 like a strict librarian. GNOME and KDE hand you a desk, a chair, and a set of drawers, then step back. i3 hands you a blank floor plan and a rulebook. You decide where the books go. You decide how the shelves stack. The librarian only enforces the rules you write down. That is why the first boot feels empty. You have to draw the floor plan before the librarian starts placing windows.
The configuration lives in ~/.config/i3/config. Fedora follows the XDG Base Directory specification, which means user overrides go in ~/.config/ and package defaults ship in /usr/share/i3/. Never edit the system defaults. They get overwritten on package updates. Edit your home directory copy. The window manager reads your copy first.
Install the window manager and generate a baseline
i3 is available in Fedora's official repositories. You do not need third-party repos for the core window manager. You will need a compositor to prevent screen tearing, a status bar to show system metrics, and a menu to launch applications. Install them together so the dependency resolver handles the X11 libraries in one transaction.
Here is how to pull the window manager, its companion tools, and a hardware-accelerated compositor from the official repos.
sudo dnf install i3 i3status i3lock dmenu picom
# i3 is the window manager. i3status feeds the bar. i3lock handles screen locking.
# dmenu provides a keyboard-driven application launcher. picom handles transparency and shadows.
# --setopt=install_weak_deps=False prevents pulling in GNOME/KDE integration packages you do not need.
Run the configuration wizard immediately after installation. It asks for your preferred modifier key, terminal emulator, browser, and editor. It then writes a functional baseline to ~/.config/i3/config.
i3-config-wizard
# The wizard parses your answers and generates a valid config file.
# It sets the $mod variable to either Mod4 (Windows key) or Mod1 (Alt).
# It creates ~/.config/i3/config if the file does not already exist.
Log out of your current session. At the display manager, click the gear icon or session selector and choose i3. Enter your password. The screen will flash once, then drop you into a black terminal window. That is the expected state. The wizard placed a terminal on workspace 1 by default.
Reboot before you debug. Half the time the symptom is gone.
Read the configuration file like a map
The configuration file is a flat list of directives. i3 reads it top to bottom. Later directives override earlier ones. There are no nested blocks. There are no tabs. Indentation is purely visual. The parser ignores whitespace except inside quoted strings.
Here is how the keybinding section maps physical keys to window manager actions.
# Set the modifier key. Mod4 is the Windows/Super key on most keyboards.
set $mod Mod4
# Bind Mod+Return to launch the terminal defined earlier.
bindsym $mod+Return exec $term
# Bind Mod+d to launch dmenu. The --dmenu flag tells dmenu to accept input from stdin.
bindsym $mod+d exec dmenu_run
# Bind Mod+Shift+q to kill the focused window. The shift modifier prevents accidental closes.
bindsym $mod+Shift+q kill
# Bind Mod+Shift+e to run i3-nagbar. It prompts you before exiting the session.
bindsym $mod+Shift+e exec i3-nagbar -m 'You pressed the exit shortcut. Do you really want to exit i3? This will end your X session.' -b 'Yes, exit i3' 'i3-msg exit'
The $mod variable is a convenience alias. You can rebind it to Mod1 if you prefer Alt. The bindsym directive maps a key combination to an action. exec runs an external command. kill destroys the focused window. move, focus, and layout manipulate the tiling tree.
The status bar configuration lives in the same file. i3status outputs JSON or plain text. i3 parses it and renders it in the bottom bar. You can swap i3status for polybar or waybar later, but i3status is faster to configure.
Here is how to route i3status output to the window manager bar.
# Define the bar appearance. Colors use hex codes.
bar {
status_command i3status
# i3status runs in the background and pipes updates to i3.
# It refreshes every 5 seconds by default.
position bottom
# Places the bar at the bottom of the screen. Change to top if you prefer.
colors {
background #000000
# Sets the bar background to pure black.
statusline #ffffff
# Sets the default text color to white.
focused_workspace #ffffff #000000
# Highlights the active workspace with white text on black.
}
}
Save the file. Press $mod+Shift+c to reload the configuration without restarting your session. i3 parses the file, applies changes to the running instance, and prints a success message to the terminal. If the syntax is broken, i3 prints the exact line number and falls back to the previous working config.
Run i3-msg reload from any terminal if you prefer a keyboard shortcut that does not depend on the current keybindings. Trust the package manager. Manual file edits drift, snapshots stay.
Verify the tiling engine is running
Open a second terminal with $mod+Return. Watch the first terminal shrink to fill half the screen. Open a third. The layout splits again. Press $mod+Enter to cycle through layout modes: default, tabbed, stacking, and splitting. The windows rearrange instantly. No dragging. No resizing handles. The geometry is calculated mathematically.
Check the internal state to confirm the workspace tree is healthy.
i3-msg -t get_workspaces
# Queries the running i3 instance for workspace metadata.
# Returns a JSON array with names, visibility status, and window counts.
# Use this to script workspace routing or verify that windows are not stuck in hidden containers.
If the output shows your workspaces and the visible flag matches what you see on screen, the tiling engine is functioning. If the bar is blank, check journalctl -xeu i3status.service or run i3status directly in a terminal to see parser errors. The status bar fails silently if the config references a missing sensor or an invalid format string.
Read the actual error before guessing.
Common pitfalls and what the error looks like
The most frequent issue is modifier key confusion. Laptops often map the Windows key to Mod4. Some compact keyboards map it to Mod1 or Control. If $mod+d does nothing, run xev in a terminal. Press the key you expect to be the modifier. Look for the state 0x... line. 0x40 is Mod1. 0x100 is Mod4. Update the set $mod line accordingly.
Another common trap is missing a compositor. i3 does not handle transparency, shadows, or screen tearing. Without picom, overlapping windows will flicker, and terminal backgrounds will render as solid black. Install picom, add exec --no-startup-id picom & to your config, and restart the session. The --no-startup-id flag prevents the display manager from tracking picom as a critical session process. If picom crashes, i3 will not force-log you out.
If you see [FAILED] Failed to start i3 session in the display manager, your config file likely contains a syntax error on the first few lines. i3 refuses to start if the parser cannot reach the end of the file. Run i3 -C to validate the configuration without launching the window manager.
Error: i3 config file syntax error:
Line 42: unknown command "bindkey". Did you mean "bindsym"?
The error points to the exact line. bindkey was deprecated years ago. bindsym is the current standard. Fix the typo, save, and try again.
SELinux denials rarely block i3, but they can block the status bar from reading hardware sensors. If i3status shows blank CPU or memory fields, check journalctl -t setroubleshoot. The one-line summary will tell you which process was denied access. Run restorecon -Rv ~/.config/i3/ to fix context labels if you copied the config from a non-Fedora system.
Snapshot the system before the upgrade. Future-you will thank you.
When to use i3 versus other window managers
Use i3 when you want a stable, X11-based tiling window manager with a mature configuration syntax and extensive community documentation. Use Sway when you need Wayland compatibility and drop-in i3 config compatibility for modern hardware. Use GNOME when you want a complete desktop environment with built-in settings panels, notification handling, and power management. Use KDE Plasma when you need deep customization, hardware acceleration, and a traditional desktop metaphor with optional tiling. Use Hyprland when you want GPU-accelerated animations, floating windows, and a Wayland-first architecture. Stay on i3 if you only deviate from the defaults occasionally and prefer a configuration file that reads like a checklist.