arch-i3
A one-shot bootstrap for a complete i3 desktop on a fresh Arch Linux install — starting from a system with no X server at all.
Everything is themed with Catppuccin Macchiato and typeset in Inconsolata Nerd Font.
i3-wm · polybar · rofi · dunst · polkit-gnome · thunar · kitty
i3lock-color + betterlockscreen · feh · picom
Quick start
From a TTY on a fresh install, as your normal user (not root — the scripts
call sudo where they need to):
sudo pacman -S --needed git
git clone <this-repo> ~/arch-i3
cd ~/arch-i3
./install.sh
Then log out, log back in (so the new group memberships apply) and:
startx
Look before you leap
./install.sh --dry-run # print every action, change nothing
./install.sh --list # show the stages
What the installer does
| Stage | Name | What happens |
|---|---|---|
00 |
preflight | Verifies Arch + network, enables pacman colour and parallel downloads, refreshes mirrors with reflector, runs a full pacman -Syu |
10 |
packages | Installs everything in packages/pacman.txt; detects your GPU and adds the matching Vulkan/VA-API driver |
20 |
aur | Builds yay-bin, swaps i3lock → i3lock-color, installs packages/aur.txt |
30 |
dotfiles | Copies configs into ~, helper scripts into ~/.local/bin, generates wallpapers |
40 |
services | Enables NetworkManager/bluetooth/pipewire, adds you to video input audio storage, rebuilds the font cache, primes the betterlockscreen cache |
50 |
theme | Applies the GTK/Qt/cursor/icon theme and reloads a running session |
Run a subset with --only / --skip, by number or by name:
./install.sh --only dotfiles,theme
./install.sh --skip 00,10 # configs only, no package churn
./install.sh -y # never prompt
./install.sh --multilib # also enable the [multilib] repo
Re-running is safe. Package installs use --needed, and any config file the
installer would overwrite is first moved — never deleted — into
~/.config-backup-<timestamp>/.
scripts/restore-backup.sh --list # see what's been backed up
scripts/restore-backup.sh # put the most recent backup back
Keybindings
$mod is the Super (Windows) key.
Launching
| Keys | Action |
|---|---|
$mod + Return |
kitty |
$mod + Shift + Return |
kitty, floating and centred |
$mod + e |
Thunar |
$mod + d |
rofi — application launcher |
$mod + Shift + d |
rofi — run a binary |
$mod + Tab |
rofi — window switcher |
$mod + Shift + e |
power menu (lock / logout / suspend / reboot / shutdown) |
$mod + q |
close window |
$mod + Shift + q |
xkill — click a window to kill it |
Session
| Keys | Action |
|---|---|
$mod + Shift + x |
lock the screen |
$mod + Shift + c |
reload the i3 config |
$mod + Shift + r |
restart i3 in place |
Focus and movement
| Keys | Action |
|---|---|
$mod + h/j/k/l or arrows |
move focus |
$mod + Shift + h/j/k/l |
move the window |
$mod + 1…0 |
switch workspace |
$mod + Shift + 1…0 |
send window to workspace |
Alt + Tab |
last workspace |
$mod + Ctrl + ←/→ |
previous / next workspace |
$mod + Ctrl + Shift + ←/→ |
move the workspace to another monitor |
Layout
| Keys | Action |
|---|---|
$mod + b / $mod + v |
split horizontally / vertically |
$mod + f |
fullscreen |
$mod + s / $mod + w / $mod + g |
stacking / tabbed / toggle split |
$mod + Shift + space |
float this window |
$mod + space |
focus tiling ↔ floating |
$mod + r |
resize mode (h/j/k/l, Escape to leave) |
$mod + minus / $mod + Shift + minus |
show / send to scratchpad |
$mod + plus / $mod + Shift + plus |
grow / shrink gaps |
Hardware and utilities
| Keys | Action |
|---|---|
| Volume / brightness / media keys | handled, with a dunst OSD |
Print |
full-screen screenshot |
Shift + Print |
select a region |
$mod + Print |
active window |
$mod + p |
display mode: auto / duplicate / extend / laptop-only |
$mod + n |
pop the last notification back up |
$mod + Shift + n |
dismiss all notifications |
$mod + Ctrl + n |
pause/resume notifications |
$mod + Shift + w |
random wallpaper |
Layout of this repo
install.sh orchestrator — stage runner, flags, summary
packages/
pacman.txt official repo packages
aur.txt AUR packages
scripts/
lib.sh logging, dry-run, backup-aware file installer
00-preflight.sh … 50-theme.sh
make-wallpaper.sh synthesises the Catppuccin wallpapers
restore-backup.sh undo
dotfiles/
xinitrc, xprofile, Xresources, gtkrc-2.0
config/ → ~/.config/…
i3/config window manager
polybar/config.ini bar; launch.sh detects your hardware
rofi/ config.rasi + Macchiato themes + powermenu.sh
dunst/dunstrc notifications
kitty/ kitty.conf + Macchiato colours
picom/picom.conf compositor
betterlockscreen/ lock screen colours
gtk-3.0/, gtk-4.0/, qt5ct/, xfce4/ toolkit theming
local/bin/ → ~/.local/bin/…
set-wallpaper volume brightness screenshot display restart-daemon
wallpapers/ drop your own images here; they win over generated ones
Things worth knowing
i3lock becomes i3lock-color
betterlockscreen depends on i3lock-color, an AUR fork that adds the
--*-color flags the Macchiato lock screen needs. It conflicts with and
provides the repo i3lock, so stage 20 removes the repo package first. You
still get an i3lock binary at the usual path — it just understands more flags.
The lock screen needs a cached image
betterlockscreen pre-renders blurred wallpapers instead of blurring at lock
time (that's why it's instant). Stage 40 builds that cache. After changing your
wallpaper, refresh it:
betterlockscreen -u ~/.local/share/wallpapers/your-image.png --blur 0.5
set-wallpaper <path> does this for you automatically.
Locking is wired up three ways: $mod+Shift+x, xss-lock (10-minute idle timer
and lid close, started from the i3 config), and a betterlockscreen@.service
sleep hook for suspends that happen outside the X session.
polybar adapts to the machine
~/.config/polybar/launch.sh detects your battery, AC adapter, backlight device
and network interfaces at launch and passes them in as environment variables, so
config.ini has nothing machine-specific in it. Modules with no matching
hardware (battery and backlight on a desktop) are dropped from the bar rather
than left to log errors. One bar spawns per monitor; the system tray goes on the
primary one. Logs land in ~/.cache/polybar.log.
NVIDIA
Stage 10 installs Mesa and, for Intel/AMD, the matching Vulkan driver. NVIDIA is left to you deliberately — the right package depends on your card's generation and kernel:
sudo pacman -S nvidia nvidia-utils # current cards, linux kernel
sudo pacman -S nvidia-lts nvidia-utils # linux-lts kernel
If you get tearing, uncomment nothing — picom.conf already sets
backend = "glx" and vsync = true. On a weak GPU, delete the blur block.
No display manager
The setup logs in from a TTY with startx, which keeps the boot lean. If you'd
rather have a greeter:
sudo pacman -S ly && sudo systemctl enable ly.service # minimal, TUI
# or
sudo pacman -S lightdm lightdm-gtk-greeter && sudo systemctl enable lightdm
Both read ~/.xprofile, so the environment stays identical either way.
Making it yours
Put personal i3 tweaks in ~/.config/i3/config.d/*.conf. They're included at the
end of the main config, so they override anything above them, and the installer
never touches that directory.
For everything else, edit the files in dotfiles/ and re-run:
./install.sh --only dotfiles
Changing the accent colour
The Catppuccin accent is mauve (#c6a0f6) throughout. To switch to, say,
teal, change it in five places:
dotfiles/config/i3/config client.focused
dotfiles/config/polybar/config.ini primary = / label-focused-*
dotfiles/config/rofi/themes/… selected:
dotfiles/config/dunst/dunstrc frame_color / [urgency_normal]
dotfiles/config/*/settings.ini catppuccin-macchiato-<accent>-standard+default
Troubleshooting
The bar is missing. cat ~/.cache/polybar.log. The most common cause is a
font that didn't install — check with fc-list | grep -i inconsolata.
Boxes instead of icons. The Nerd Font glyphs aren't being found. Run
fc-cache -fv, then confirm ttf-inconsolata-nerd and ttf-nerd-fonts-symbols-mono
are installed.
GTK apps look light/wrong. The AUR theme package may name its accent
directory differently. ls /usr/share/themes | grep -i catppuccin, then put the
exact name into ~/.config/gtk-3.0/settings.ini. Stage 50 tries to detect and
patch this automatically.
No sound. systemctl --user status pipewire wireplumber. A reboot after the
first install is usually what's missing.
Lock screen shows a plain grey box. The betterlockscreen cache isn't built —
run betterlockscreen -u <image>.
i3 won't start. i3 -C validates the config and prints the offending line.