swf.wtf
Feb 26, 2026 guide arch hyprland wayland

Hyprland on Base Arch Linux.
// from tty to usable desktop.

This guide assumes you already have a working base Arch install (network, users, bootloader done). We install Hyprland and enough core tools to make it daily-usable without pulling in someone else's full dotfiles stack.

# sudo pacman -Syu
sync and update base system
# sudo pacman -S --needed hyprland waybar wofi kitty
install compositor and core desktop tools
# Hyprland
// contents
Before you start GPU and session prerequisites Install Hyprland stack Create minimal Hyprland config Start Hyprland from tty Optional: use SDDM First boot checks Common issues Sources

Before you start

// expectation check
Hyprland is a compositor, not a full desktop environment. You need to install and configure your own bar, launcher, notifications, lock screen, and wallpaper tools.

GPU and session prerequisites

Install the driver stack that matches your hardware before debugging Hyprland itself.

driver examples 
# Intel / AMD (Mesa stack)
sudo pacman -S --needed mesa vulkan-icd-loader

# AMD Vulkan userspace
sudo pacman -S --needed vulkan-radeon

# Intel Vulkan userspace
sudo pacman -S --needed vulkan-intel

# NVIDIA proprietary stack (if you use NVIDIA)
sudo pacman -S --needed nvidia nvidia-utils

Install Hyprland stack

This is a practical baseline: compositor, portal, bar, launcher, terminal, wallpaper, lock, idle, clipboard, screenshot, and audio/session pieces.

core packages 
sudo pacman -Syu

sudo pacman -S --needed hyprland xdg-desktop-portal xdg-desktop-portal-hyprland
sudo pacman -S --needed waybar wofi kitty hyprpaper hyprlock hypridle hyprpolkitagent
sudo pacman -S --needed wl-clipboard grim slurp
sudo pacman -S --needed pipewire wireplumber pipewire-audio pavucontrol
sudo pacman -S --needed ttf-dejavu ttf-jetbrains-mono-nerd noto-fonts noto-fonts-emoji
// portal note
Screen sharing and many flatpak/app file picker flows rely on xdg-desktop-portal plus a backend like xdg-desktop-portal-hyprland.

Create minimal Hyprland config

Copy the packaged default config, then set terminal/launcher and startup services.

main config 
mkdir -p ~/.config/hypr
cp /usr/share/hypr/hyprland.conf ~/.config/hypr/hyprland.conf
nvim ~/.config/hypr/hyprland.conf

# ensure these lines exist in hyprland.conf:
$terminal = kitty
$menu = wofi --show drun
bind = SUPER, Return, exec, $terminal
bind = SUPER, D, exec, $menu
exec-once = waybar
exec-once = hyprpaper
exec-once = hyprpolkitagent
wallpaper config 
mkdir -p ~/Pictures/wallpapers
# put a wallpaper image at ~/Pictures/wallpapers/default.jpg first
nvim ~/.config/hypr/hyprpaper.conf

# hyprpaper.conf:
preload = ~/Pictures/wallpapers/default.jpg
wallpaper = ,~/Pictures/wallpapers/default.jpg
splash = false
ipc = on

Start Hyprland from tty

Use tty launch first. It is the fastest way to debug without introducing display-manager variables.

manual start 
Hyprland
optional auto-start on tty1 
nvim ~/.zprofile

# add:
if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
  exec Hyprland
fi

Optional: use SDDM

If you prefer a graphical login manager instead of tty launch:

sddm path 
sudo pacman -S --needed sddm
sudo systemctl enable sddm
reboot
// first setup recommendation
Validate Hyprland from tty first, then add SDDM after your user config is known-good.

First boot checks

sanity checks 
echo $XDG_SESSION_TYPE # should print wayland
hyprctl monitors
systemctl --user status xdg-desktop-portal.service xdg-desktop-portal-hyprland.service --no-pager
pactl info | grep \"Server Name\"
nmcli general status

Common issues

Black screen or immediate exit
Switch to tty, run Hyprland directly, then inspect logs with journalctl --user -b --no-pager. Most failures are driver/session/package gaps.
Screen sharing or picker issues
Confirm both portal packages are installed. Then restart user portals: systemctl --user restart xdg-desktop-portal xdg-desktop-portal-hyprland.
No audio devices
Check PipeWire and WirePlumber user services and relogin: systemctl --user status pipewire wireplumber --no-pager.
Polkit prompts do not appear
Ensure hyprpolkitagent is installed and exec-once = hyprpolkitagent is present in hyprland.conf.

Sources