Hyprland Setup

Hyprland is a dynamic tiling Wayland compositor. This covers the full Hyprland ecosystem setup after Base Install.

Installation

sudo pacman -S \
  hyprland \
  hyprlock \
  hypridle \
  hyprpaper \
  hyprpicker \
  hyprcursor \
  hyprsunset \
  xdg-desktop-portal-hyprland \
  hyprpolkitagent

Full Package List

All Hyprland ecosystem packages I have installed:

• hyprcursor
• hyprgraphics
• hypridle
• hyprland
• hyprland-guiutils
• hyprland-protocols
• hyprland-qt-support
• hyprlang
• hyprlock
• hyprpaper
• hyprpicker
• hyprpolkitagent
• hyprpwcenter
• hyprsunset
• hyprtoolkit
• hyprutils
• hyprwayland-scanner
• hyprwire
• xdg-desktop-portal-hyprland

AUR Packages

paru -S hyprshutdown

See hyprshutdown for build instructions if the AUR version is outdated.

Related Components

• Ashell — Status bar
• Mako — Notifications
• hyprlock — Screen lock with fingerprint support
• hyprshutdown — Graceful shutdown animations
• fprintd — Fingerprint authentication
• Plymouth — Boot splash screen

Configuration Structure

My config uses includes to keep the main file clean and modular.

Directory Layout

~/.config/hypr/
├── hyprland.conf           # Main config (mostly defaults + sources)
├── hyprland.conf.d/        # Modular config includes
│   ├── monitors            # Display configuration
│   ├── programs            # Variable definitions ($terminal, etc.)
│   ├── autostart           # exec-once statements
│   ├── general             # Gaps, borders, layout
│   └── keybinds            # Custom keybind overrides
├── hyprlock.conf           # Lock screen config
├── hypridle.conf           # Idle behavior config
├── hyprpaper.conf          # Wallpaper config
└── hyprsunset.conf         # Night light config

Using Includes

The main hyprland.conf uses source statements to pull in modular configs:

# In hyprland.conf
source = ~/.config/hypr/hyprland.conf.d/monitors
source = ~/.config/hypr/hyprland.conf.d/programs
source = ~/.config/hypr/hyprland.conf.d/autostart
source = ~/.config/hypr/hyprland.conf.d/general
source = ~/.config/hypr/hyprland.conf.d/keybinds

Why Includes?

1. Keep defaults intact — Main config stays close to upstream defaults
2. Easy diffing — Can compare against new Hyprland releases
3. Modular changes — Edit just monitors or keybinds without touching the rest
4. Machine-specific — Different monitor configs per machine, same base

Example: programs

Define variables in one place:

# ~/.config/hypr/hyprland.conf.d/programs
$terminal = kitty
$filemanager = thunar
$menu = walker

Example: autostart

All startup applications:

# ~/.config/hypr/hyprland.conf.d/autostart
 
# Hypr ecosystem
exec-once = hyprpaper & hypridle & hyprsunset
 
# Status bar
exec-once = ashell &
 
# Services
exec-once = systemctl --user start elephant
exec-once = systemctl --user start hyprpolkitagent
 
# Apps
exec-once = walker --gapplication-service
exec-once = udiskie &
exec-once = wl-paste --watch cliphist store
exec-once = tailscale up
exec-once = protonmail-bridge-core

Example: keybinds

Override and add custom bindings:

# ~/.config/hypr/hyprland.conf.d/keybinds
$mainModS = SUPER_SHIFT
 
# Unbind defaults I don't want
unbind = $mainMod, Q
unbind = $mainMod, C
unbind = $mainMod, R
 
# My bindings
bind = $mainMod, Return, exec, $terminal
bind = $mainMod, Q, killactive
bind = $mainModS, B, exec, qutebrowser
bind = $mainMod, Space, exec, $menu

Idle Management (hypridle)

Config: ~/.config/hypr/hypridle.conf

My idle sequence:

1. 2.5 min — Dim screen + keyboard backlight
2. 5 min — Lock screen
3. 5.5 min — Turn off display
4. 30 min — Suspend

Key settings:

general {
    lock_cmd = pidof hyprlock || hyprlock  # Prevent multiple instances
    before_sleep_cmd = loginctl lock-session
    after_sleep_cmd = hyprctl dispatch dpms on
}

Brightness Control

Install brightnessctl:

sudo pacman -S brightnessctl

Framework laptop keybinds (already in default config):

bindel = ,XF86MonBrightnessUp, exec, brightnessctl -e4 -n2 set 5%+
bindel = ,XF86MonBrightnessDown, exec, brightnessctl -e4 -n2 set 5%-

Tips

• Use hyprctl to interact with Hyprland from scripts
• hyprctl monitors — list displays
• hyprctl clients — list windows
• hyprctl reload — reload config without restart