You installed i3 and now you have a black screen
You installed Fedora Workstation and decided GNOME is too heavy. You installed i3, logged in, and now you are staring at a black screen with a single prompt. Or you pressed a key combo and nothing happened because the config file is a wall of comments. You need a working setup, not a tutorial on every possible flag.
i3 is a tiling window manager. It does not manage panels, notifications, or power settings by default. It places windows in a tree structure and lets you navigate with keyboard shortcuts. The configuration lives in a plain text file. i3 reads this file on startup and can reload it instantly. This means you can edit the config, press a key, and see the change immediately. No reboot. No logout. If you break the config, i3 tells you exactly what line failed.
Reload the config before you debug. i3 tells you the exact line number.
What is actually happening
i3 divides the screen into containers. Each container holds a window or other containers. You navigate this tree with keyboard shortcuts. This mental model is essential. If you do not understand containers, the shortcuts will feel random.
The configuration file controls three things. Keybindings map keys to actions. Startup commands run programs when i3 starts. Window rules move specific applications to specific workspaces.
i3 copies a default config to ~/.config/i3/config on the first run. This file is in your home directory. Package updates will not overwrite it. This is safe. You can edit this file with any text editor. i3 parses it line by line. If a line is invalid, i3 prints an error and skips that line. The rest of the config still loads.
Keep a TTY open. A broken config can lock you out of the graphical session.
Install i3 and essential tools
Here is how to install i3 and the tools you will need immediately. i3 requires a status bar and a notification daemon to function like a complete desktop. Fedora provides these in the official repositories.
sudo dnf install i3 i3status dunst -y
# -y skips the confirmation prompt for automation
# i3status provides the data for the status bar
# dunst handles desktop notifications from applications
After installation, log out of your current session. At the GNOME login screen, click the gear icon in the bottom-right corner and select i3 from the list. If you are already logged in and want to test immediately, you can start a new i3 instance in a separate terminal. This runs i3 inside the current session and is useful for testing config changes without logging out.
i3
# Starts i3 in the current terminal
# Press Mod+Shift+e to exit i3 and return to the terminal
Run the install command once. The packages persist across reboots.
Configure the core settings
Here is how to set up the core configuration. Open the config file in your terminal editor. The default file contains examples and comments. You can delete the comments to reduce noise, but keep the structure.
nano ~/.config/i3/config
# nano opens the file in the terminal
# ~/.config/i3/config is the user-specific config location
Add or modify these lines to define your modifier key, terminal shortcut, and startup applications. The $mod variable is defined near the top of the file. It usually maps to Mod4, which is the Windows/Super key.
# Set the modifier key. $mod is usually the Super/Windows key.
set $mod Mod4
# Bind keys to actions. $mod+Return runs the terminal.
bindsym $mod+Return exec alacritty
# Start the notification daemon without a startup notification.
exec --no-startup-id dunst
# Define the font for the bar and window titles.
font pango:DejaVu Sans Mono 10
The set command defines a variable for reuse. The bindsym command maps a key combo to a command. The exec command runs a program on startup. The --no-startup-id flag suppresses the GNOME startup notification, which is unnecessary in i3.
After saving the file, press Mod+Shift+r to reload the configuration. i3 will apply the changes instantly. If the reload fails, i3 prints an error message in the terminal where you started i3. Check the line number and fix the syntax.
Reload the config before you panic. i3 tells you the line number.
Manage workspaces and window rules
Here is how to organize your windows. Workspaces are virtual desktops. You can assign specific applications to specific workspaces automatically. This keeps your workflow organized without manual dragging.
# Move Firefox to workspace 2 automatically.
for_window [class="Firefox"] move container to workspace 2
# Move terminal windows to workspace 3.
for_window [class="Alacritty"] move container to workspace 3
# Switch to workspace 2 when Firefox starts.
for_window [class="Firefox"] move container to workspace 2, workspace 2
The for_window command matches windows by properties. The class property is the X11 window class. You can find this class by running xprop and clicking on the window. The move container to workspace command moves the window to the specified workspace. The second example also switches to that workspace immediately.
Use xprop to identify window properties. Guessing the class name leads to rules that never match.
Verify the setup
Here is how to check that i3 is responding to commands. i3 exposes an IPC interface that allows you to query the state and send commands. This is useful for scripting and debugging.
i3-msg -t get_workspaces
# -t get_workspaces queries the workspace state
# JSON output confirms i3 is running and responsive
The output is a JSON array of workspaces. Each entry shows the name, output, and focus state. If you see this output, i3 is running correctly. If you see Error: IPC socket not found, i3 is not running or the socket path is incorrect.
Run i3-msg -t get_workspaces to confirm the IPC is alive.
Common pitfalls and errors
The most common error is a syntax mistake in the config file. i3 will print Error: syntax error in config file at line 123 in the terminal where you started i3. Check the line number. Missing braces or typos in keybindings are the usual culprits.
If you see Failed to start i3bar, check that i3status is installed and the bar block is uncommented in the config. The bar block tells i3 to start the status bar. Without it, you will have no bar.
SELinux rarely blocks i3 when installed from official repositories. If you get denials, check journalctl -t setroubleshoot. This command shows SELinux alerts with human-readable summaries. Read the summary before disabling SELinux. Most denials are caused by custom scripts or non-standard paths.
If the config is broken and i3 refuses to start, you need to edit the file from outside the session. Switch to a TTY with Ctrl+Alt+F3. Log in. Edit the config. Switch back with Ctrl+Alt+F1. This saves you from a reinstall.
Check the line number in the error message. Fix the syntax before reloading.
When to use i3 vs alternatives
Use i3 when you want a stable, X11-based tiling window manager with a mature ecosystem. Use sway when you need Wayland support and a drop-in replacement for i3. Use GNOME when you prefer a mouse-driven workflow with integrated settings and extensions. Use KDE Plasma when you want deep customization of the desktop environment without writing config files. Stay on i3 if you value keyboard efficiency and a minimal resource footprint.
Test changes in a VM first. A bad keybinding can make your system unresponsive.