---
publish: true
permalink: /os/hyprland
title: Hyprland Setup
created: 2026-01-29T15:09:13.502-07:00
modified: 2026-02-05T12:18:02.155-07:00
tags:
  - hyprland
  - wayland
  - desktop
cssclasses: ""
---

Hyprland is a dynamic tiling Wayland compositor. This covers the full Hyprland ecosystem setup after [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/Base Install]].

## Installation

```bash
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

```bash
paru -S hyprshutdown
```

See [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/hyprshutdown]] for build instructions if the AUR version is outdated.

## Related Components

- [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/Ashell]] — Status bar
- [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/Mako]] — Notifications
- [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/hyprlock]] — Screen lock with fingerprint support
- [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/hyprshutdown]] — Graceful shutdown animations
- [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/fprintd]] — Fingerprint authentication
- [[10-19 LIFE/13 TECH SETUP/13.13 OS SETUP/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:

```bash
# 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:
```bash
# ~/.config/hypr/hyprland.conf.d/programs
$terminal = kitty
$filemanager = thunar
$menu = walker
```

### Example: autostart

All startup applications:
```bash
# ~/.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:
```bash
# ~/.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:
```bash
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`:
```bash
sudo pacman -S brightnessctl
```

Framework laptop keybinds (already in default config):
```bash
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