EndeavourOS + i3

Source: endeavouros.com / i3wm.org / archlinux.wiki Author: Johan Beysen

---

1. What Is EndeavourOS?

EndeavourOS is an Arch-based Linux distribution that makes Arch accessible without the manual installation pain — without abandoning the Arch philosophy. No bloat, no opinions about what you should install, just a working Arch system with a friendly installer (Calamares).

Characteristics:

Aspect	Detail
Base	Arch Linux
Package manager	pacman + yay (AUR)
Init system	systemd
Releases	Rolling release (never reinstall)
Community edition	i3, XFCE, LXQT, Openbox, BSPWM, ...
Flagship	Online installer with a choice of DE/WM

---

2. What Is i3?

i3 is a tiling window manager — not a full desktop environment. That means: no file manager that opens automatically, no systray out of the box, no mouse-driven workflow. Everything works through keyboard shortcuts and configuration files.

2.1 Tiling vs Floating

	Tiling (i3)	Floating (GNOME/KDE)
Windows	Fill the screen automatically	Float freely
Mouse	Optional	Central
Productivity	High after a learning curve	Immediately intuitive
Configuration	Text file	GUI
Memory usage	~200-400MB	800MB - 2GB+

i3 vs i3-gaps

The EOS community edition ships i3-gaps (now merged into i3 4.22+) — this adds gaps between windows for aesthetics. Standard i3 doesn't have this.

2.2 Basic Concepts

• Workspace — a virtual desktop (1 through 10)
• Container — every window sits inside a container
• Layout — split horizontally, vertically or tabbed
• Scratchpad — a hidden workspace for temporary windows
• Bar — the status bar (i3bar or polybar)
• Mod key — your modifier key (default: Super/Win or Alt)

---

3. Configuration File

# Location
~/.config/i3/config

# Reload without logging out
$mod+Shift+r

# Restart i3 (a heavier refresh)
$mod+Shift+e → Restart

3.1 Setting the Mod Key

# In ~/.config/i3/config:
set $mod Mod4   # Super/Win key (recommended)
# set $mod Mod1 # Alt key

3.2 Font

font pango:JetBrainsMono Nerd Font 10
# or
font pango:monospace 10

---

4. Default Key Bindings

4.1 Windows

Shortcut	Action
$mod+Enter	Open a terminal
$mod+d	App launcher (dmenu/rofi)
$mod+q	Close a window
$mod+f	Fullscreen toggle
$mod+Shift+Space	Floating toggle
$mod+Space	Switch focus floating/tiling
$mod+h/j/k/l	Switch focus (vim-style)
$mod+←/↓/↑/→	Switch focus (arrow keys)
$mod+Shift+h/j/k/l	Move a window
$mod+Shift+←/↓/↑/→	Move a window (arrow keys)

4.2 Layout

Shortcut	Action
$mod+e	Split toggle (horizontal/vertical)
$mod+s	Stacked layout
$mod+w	Tabbed layout
$mod+r	Resize mode
$mod+a	Focus the parent container

4.3 Workspaces

Shortcut	Action
$mod+1 through $mod+0	Go to workspace 1-10
$mod+Shift+1 through $mod+Shift+0	Move a window to a workspace
$mod+Tab	Previous workspace

4.4 System

Shortcut	Action
$mod+Shift+r	Reload config
$mod+Shift+q	Exit i3
$mod+Shift+e	Exit menu

---

5. Adjusting the Config

5.1 Setting the Terminal

# In ~/.config/i3/config:
set $terminal alacritty
# or: kitty, wezterm, xterm, urxvt

bindsym $mod+Return exec $terminal

5.2 App Launcher

# Rofi (recommended over dmenu)
bindsym $mod+d exec --no-startup-id rofi -show drun -show-icons

# Rofi also for window switching
bindsym $mod+Tab exec --no-startup-id rofi -show window

# dmenu (default, minimalist)
bindsym $mod+d exec --no-startup-id dmenu_run

5.3 Autostart

# Apps to start on login
exec --no-startup-id nm-applet                    # NetworkManager icon
exec --no-startup-id picom                        # Compositor
exec --no-startup-id feh --bg-scale ~/wallpaper.jpg  # Wallpaper
exec --no-startup-id dunst                        # Notifications
exec --no-startup-id xset r rate 300 50           # Keyboard repeat rate
exec --no-startup-id numlockx on                  # Numlock on

# exec vs exec_always
# exec          → only on first start
# exec_always   → also after $mod+Shift+r (config reload)
exec_always --no-startup-id picom --config ~/.config/picom/picom.conf

5.4 Workspace Layout

# Naming workspaces
set $ws1  "1: "
set $ws2  "2: "
set $ws3  "3: "
set $ws4  "4: "
set $ws5  "5: "

# Automatically sending windows to a workspace
assign [class="firefox"]    $ws2
assign [class="Code"]       $ws3
assign [class="discord"]    $ws5
assign [class="Spotify"]    $ws5

Finding a window's class

xprop | grep WM_CLASS
# Then click on the window

5.5 Gaps (spacing between windows)

# In ~/.config/i3/config:
gaps inner 8
gaps outer 4

# Per workspace
workspace $ws1 gaps inner 0   # No gaps on workspace 1

# Smart gaps (no gaps if there's only 1 window)
smart_gaps on
smart_borders on

5.6 Floating Windows

# Specific apps always floating
for_window [class="Pavucontrol"] floating enable
for_window [class="Nm-connection-editor"] floating enable
for_window [title="File Transfer*"] floating enable
for_window [window_role="pop-up"] floating enable
for_window [window_role="bubble"] floating enable

# Centering a floating window
for_window [class="Pavucontrol"] move position center

5.7 Colors

# Window border colors
# class                 border  backgr  text    indicator child_border
client.focused          #4c7899 #285577 #ffffff #2e9ef4   #285577
client.focused_inactive #333333 #5f676a #ffffff #484e50   #5f676a
client.unfocused        #333333 #222222 #888888 #292d2e   #222222
client.urgent           #2f343a #900000 #ffffff #900000   #900000

# Border thickness
default_border pixel 2
default_floating_border pixel 2

5.8 Custom Shortcuts

# Screenshots
bindsym Print exec --no-startup-id scrot ~/Screenshots/%Y-%m-%d_%H%M%S.png
bindsym $mod+Print exec --no-startup-id scrot -s ~/Screenshots/%Y-%m-%d_%H%M%S.png

# Volume
bindsym XF86AudioRaiseVolume exec --no-startup-id pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym XF86AudioLowerVolume exec --no-startup-id pactl set-sink-volume @DEFAULT_SINK@ -5%
bindsym XF86AudioMute exec --no-startup-id pactl set-sink-mute @DEFAULT_SINK@ toggle

# Brightness
bindsym XF86MonBrightnessUp exec --no-startup-id brightnessctl set +5%
bindsym XF86MonBrightnessDown exec --no-startup-id brightnessctl set 5%-

# Lock screen
bindsym $mod+l exec --no-startup-id i3lock -c 000000

# File manager
bindsym $mod+shift+f exec --no-startup-id thunar

# Browser
bindsym $mod+shift+b exec --no-startup-id firefox

---

6. Status Bar — i3bar vs Polybar

6.1 i3bar (built in)

bar {
    status_command i3status
    position top
    font pango:JetBrainsMono Nerd Font 10

    colors {
        background #282828
        statusline #ebdbb2
        separator  #504945

        focused_workspace  #458588 #458588 #282828
        active_workspace   #282828 #3c3836 #ebdbb2
        inactive_workspace #282828 #282828 #a89984
        urgent_workspace   #cc241d #cc241d #282828
    }
}

~/.config/i3status/config:

general {
    colors = true
    interval = 5
}

order += "wireless _first_"
order += "ethernet _first_"
order += "memory"
order += "cpu_usage"
order += "battery all"
order += "tztime local"

wireless _first_ {
    format_up = "W: (%quality at %essid) %ip"
    format_down = "W: down"
}

memory {
    format = "RAM: %used / %total"
    threshold_degraded = "10%"
}

cpu_usage {
    format = "CPU: %usage"
}

battery all {
    format = "%status %percentage %remaining"
}

tztime local {
    format = "%d-%m-%Y %H:%M:%S"
}

6.2 Polybar (recommended)

Polybar is more powerful and more customizable than i3bar.

# Installing
sudo pacman -S polybar
# or via yay if it's not in the repos
yay -S polybar

# Config location
~/.config/polybar/config.ini

# Starting it (add to the i3 config)
exec_always --no-startup-id ~/.config/polybar/launch.sh

~/.config/polybar/launch.sh:

#!/bin/bash
killall -q polybar
while pgrep -u $UID -x polybar >/dev/null; do sleep 1; done
polybar main &

A basic polybar config:

[colors]
background = #282828
foreground = #ebdbb2
primary    = #458588
alert      = #cc241d

[bar/main]
monitor = ${env:MONITOR:}
width = 100%
height = 28
background = ${colors.background}
foreground = ${colors.foreground}
font-0 = JetBrainsMono Nerd Font:size=10
modules-left   = i3 xwindow
modules-center = date
modules-right  = pulseaudio memory cpu battery

[module/i3]
type = internal/i3
format = <label-state> <label-mode>
label-focused         = %name%
label-focused-padding = 2
label-unfocused       = %name%
label-unfocused-padding = 2
label-urgent          = %name%
label-urgent-padding  = 2

[module/date]
type = internal/date
interval = 1
date = %d-%m-%Y
time = %H:%M:%S
label = %date%  %time%

[module/pulseaudio]
type = internal/pulseaudio
label-volume =  %percentage%%
label-muted  = 婢 muted

[module/memory]
type = internal/memory
interval = 2
label =  %percentage_used%%

[module/cpu]
type = internal/cpu
interval = 2
label =  %percentage%%

[module/battery]
type = internal/battery
battery = BAT0
adapter = AC
label-charging    =  %percentage%%
label-discharging =  %percentage%%
label-full        =  Full

---

7. Compositor — Picom

Picom provides transparency, shadows and animations.

sudo pacman -S picom

~/.config/picom/picom.conf:

# Shadows
shadow = true
shadow-radius = 10
shadow-offset-x = -10
shadow-offset-y = -10
shadow-opacity = 0.5
shadow-exclude = [
    "class_g = 'i3-frame'",
    "_GTK_FRAME_EXTENTS@:c"
];

# Transparency
inactive-opacity = 0.9
active-opacity = 1.0
frame-opacity = 1.0
inactive-opacity-override = false

# Blur (requires a picom fork with blur support, e.g. picom-jonaburg)
blur-method = "dual_kawase"
blur-strength = 5
blur-background = true

# Animations (picom-jonaburg)
transition-length = 150
transition-pow-x = 0.1
transition-pow-y = 0.1
transition-pow-w = 0.1
transition-pow-h = 0.1
size-transition = true

# Backend
backend = "glx"
vsync = true

# Starting it
exec_always --no-startup-id picom --config ~/.config/picom/picom.conf -b

---

8. Essential Tools for i3

# App launcher
sudo pacman -S rofi

# Notifications
sudo pacman -S dunst

# Wallpaper
sudo pacman -S feh
sudo pacman -S nitrogen    # GUI alternative

# Lock screen
sudo pacman -S i3lock
yay -S i3lock-color        # More options

# Screenshot
sudo pacman -S scrot
sudo pacman -S flameshot    # GUI alternative

# Clipboard manager
sudo pacman -S xclip
sudo pacman -S clipmenu

# Volume
sudo pacman -S pavucontrol  # GUI
sudo pacman -S pamixer       # CLI

# Brightness
sudo pacman -S brightnessctl

# Network applet
sudo pacman -S network-manager-applet

# File manager
sudo pacman -S thunar        # Lightweight
sudo pacman -S ranger        # TUI (terminal)

---

9. EOS Package Management

9.1 pacman

# Update the entire system
sudo pacman -Syu

# Install a package
sudo pacman -S package

# Remove (+ unused deps)
sudo pacman -Rs package

# Search
pacman -Ss searchterm

# Info
pacman -Si package           # Repository
pacman -Qi package           # Installed

# Clean up orphaned packages
sudo pacman -Rns $(pacman -Qdtq)

# Clean the cache
sudo pacman -Sc             # Remove non-installed packages
sudo paccache -r            # Keep 3 versions (pacman-contrib)

# Which package provides this file?
pacman -Qo /usr/bin/i3

# All files owned by a package
pacman -Ql i3-wm

9.2 yay (AUR Helper)

# Installing (if not already present on EOS)
sudo pacman -S --needed git base-devel
git clone https://aur.archlinux.org/yay.git
cd yay && makepkg -si

# Usage — same syntax as pacman + AUR
yay -Syu                    # Update everything incl. AUR
yay -S package               # Install (also from AUR)
yay -Ss searchterm            # Search incl. AUR
yay -Yc                     # Remove orphaned AUR packages

9.3 EOS-Specific Tools

# EOS update tool (GUI)
eos-update

# Update mirrors
eos-rankmirrors

# Welcome app
eos-welcome

# View the EOS log
eos-log-tool

---

10. Theming & Rice

10.1 GTK Theme

# Installing
sudo pacman -S lxappearance    # GUI configuration
sudo pacman -S nwg-look        # Wayland alternative

# Popular themes
yay -S catppuccin-gtk-theme-mocha
yay -S gruvbox-dark-gtk
yay -S dracula-gtk-theme
sudo pacman -S arc-gtk-theme
sudo pacman -S materia-gtk-theme

# Icons
sudo pacman -S papirus-icon-theme
yay -S catppuccin-papirus-folders

10.2 Fonts

# Nerd Fonts (for icons in the terminal/polybar)
sudo pacman -S ttf-jetbrains-mono-nerd
sudo pacman -S ttf-hack-nerd
sudo pacman -S ttf-firacode-nerd
yay -S nerd-fonts-complete    # All Nerd Fonts

# Emoji
sudo pacman -S noto-fonts-emoji
sudo pacman -S ttf-twemoji

10.3 Terminal Theme (Alacritty)

~/.config/alacritty/alacritty.toml:

[colors.primary]
background = "#1e1e2e"
foreground = "#cdd6f4"

[colors.normal]
black   = "#45475a"
red     = "#f38ba8"
green   = "#a6e3a1"
yellow  = "#f9e2af"
blue    = "#89b4fa"
magenta = "#f5c2e7"
cyan    = "#94e2d5"
white   = "#bac2de"

[font.normal]
family = "JetBrainsMono Nerd Font"
style  = "Regular"

[font]
size = 11.0

10.4 Rofi Theme

# Selecting a theme
rofi-theme-selector

# Config location
~/.config/rofi/config.rasi

# Installing the Catppuccin theme
yay -S rofi-lbonn-git   # Wayland version

~/.config/rofi/config.rasi:

configuration {
    modi: "drun,run,window";
    show-icons: true;
    icon-theme: "Papirus-Dark";
    font: "JetBrainsMono Nerd Font 12";
}

@import "~/.config/rofi/catppuccin-mocha.rasi"

---

11. Multi-Monitor

# Detecting monitors
xrandr

# Configuring a monitor
xrandr --output HDMI-1 --auto --right-of eDP-1

# In the i3 config:
exec --no-startup-id xrandr --output HDMI-1 --auto --right-of eDP-1

# Linking a workspace to a monitor
workspace $ws1 output eDP-1
workspace $ws2 output eDP-1
workspace $ws3 output HDMI-1
workspace $ws4 output HDMI-1

# arandr = GUI for xrandr
sudo pacman -S arandr

# autorandr — auto-detection of monitor setups
sudo pacman -S autorandr
autorandr --save home
autorandr --save work
autorandr --change   # switch automatically

---

12. Managing Dotfiles

Dotfiles are your configuration files. Keeping them in Git makes recovery after a reinstall trivial.

# Method 1: Bare Git Repository (recommended)
git init --bare $HOME/.dotfiles
alias config='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
config config --local status.showUntrackedFiles no

# Usage
config add ~/.config/i3/config
config add ~/.config/alacritty/alacritty.toml
config add ~/.config/polybar/config.ini
config commit -m "Add i3 and alacritty config"
config push

# Restoring on a new system
git clone --bare <your-repo-url> $HOME/.dotfiles
alias config='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
config checkout

# Method 2: Symlinks with stow
sudo pacman -S stow
cd ~/dotfiles
stow i3          # Creates symlinks from dotfiles/i3/ to ~/.config/i3/
stow alacritty

Which files?

~/.config/i3/config
~/.config/polybar/
~/.config/alacritty/
~/.config/rofi/
~/.config/picom/
~/.config/dunst/
~/.config/ranger/
~/.bashrc or ~/.zshrc
~/.config/starship.toml

---

13. Troubleshooting

13.1 i3 Won't Start

# Viewing the log
~/.local/share/i3/log
journalctl --user -u i3 -b

# Checking config syntax
i3 -C   # Validates the config without starting

13.2 Application Crashes / Hangs

# Force-close a window
$mod+Shift+q

# Or via a terminal
xkill       # The cursor turns into an X, click on the window

13.3 Display Issues

# Display info
xdpyinfo | grep dimensions
xrandr --listmonitors

# HiDPI scaling
echo 'Xft.dpi: 192' >> ~/.Xresources
xrdb ~/.Xresources

# In the i3 config for HiDPI:
exec --no-startup-id xrandr --dpi 192

13.4 Sound Card Issues

# Restarting PulseAudio
pulseaudio --kill && pulseaudio --start

# PipeWire status (the modern replacement)
systemctl --user status pipewire
systemctl --user status wireplumber

# Available sinks
pactl list sinks short

---

14. Handy i3 Commands via CLI

# i3-msg — send commands to i3
i3-msg workspace 3
i3-msg floating toggle
i3-msg fullscreen toggle
i3-msg layout tabbed
i3-msg exec firefox

# Viewing the tree structure
i3-msg -t get_tree | python3 -m json.tool | less

# Current workspace info
i3-msg -t get_workspaces | python3 -m json.tool

---

15. Minimal i3 Config (Starting Point)

# ~/.config/i3/config — clean starting point

set $mod Mod4
set $terminal alacritty
set $browser firefox
set $files thunar

font pango:JetBrainsMono Nerd Font 10

# Floating modifier
floating_modifier $mod

# Borders
default_border pixel 2
default_floating_border pixel 2
gaps inner 8
gaps outer 0
smart_gaps on

# Basic shortcuts
bindsym $mod+Return exec $terminal
bindsym $mod+d exec rofi -show drun -show-icons
bindsym $mod+Shift+f exec $files
bindsym $mod+Shift+b exec $browser
bindsym $mod+q kill

# Focus
bindsym $mod+h focus left
bindsym $mod+j focus down
bindsym $mod+k focus up
bindsym $mod+l focus right
bindsym $mod+Left focus left
bindsym $mod+Down focus down
bindsym $mod+Up focus up
bindsym $mod+Right focus right

# Moving
bindsym $mod+Shift+h move left
bindsym $mod+Shift+j move down
bindsym $mod+Shift+k move up
bindsym $mod+Shift+l move right

# Layout
bindsym $mod+e layout toggle split
bindsym $mod+s layout stacking
bindsym $mod+w layout tabbed
bindsym $mod+f fullscreen toggle
bindsym $mod+Shift+space floating toggle

# Workspaces
bindsym $mod+1 workspace number 1
bindsym $mod+2 workspace number 2
bindsym $mod+3 workspace number 3
bindsym $mod+4 workspace number 4
bindsym $mod+5 workspace number 5
bindsym $mod+Shift+1 move container to workspace number 1
bindsym $mod+Shift+2 move container to workspace number 2
bindsym $mod+Shift+3 move container to workspace number 3
bindsym $mod+Shift+4 move container to workspace number 4
bindsym $mod+Shift+5 move container to workspace number 5

# Volume
bindsym XF86AudioRaiseVolume exec pactl set-sink-volume @DEFAULT_SINK@ +5%
bindsym XF86AudioLowerVolume exec pactl set-sink-volume @DEFAULT_SINK@ -5%
bindsym XF86AudioMute exec pactl set-sink-mute @DEFAULT_SINK@ toggle

# Screen
bindsym Print exec scrot ~/Screenshots/%Y%m%d_%H%M%S.png
bindsym $mod+l exec i3lock -c 000000

# i3 management
bindsym $mod+Shift+r restart
bindsym $mod+Shift+e exec i3-nagbar -t warning -m 'Exit?' -B 'Yes' 'i3-msg exit'

# Resize mode
mode "resize" {
    bindsym h resize shrink width 5 px or 5 ppt
    bindsym j resize grow height 5 px or 5 ppt
    bindsym k resize shrink height 5 px or 5 ppt
    bindsym l resize grow width 5 px or 5 ppt
    bindsym Return mode "default"
    bindsym Escape mode "default"
}
bindsym $mod+r mode "resize"

# Autostart
exec --no-startup-id nm-applet
exec --no-startup-id picom -b
exec --no-startup-id feh --bg-scale ~/wallpaper.jpg
exec_always --no-startup-id ~/.config/polybar/launch.sh

# Status bar
bar {
    status_command i3status
    position top
}

---