Hyprland

Quick Reference

# Start Hyprland
Hyprland

# Reload configuration
hyprctl reload

# List windows
hyprctl clients

# List workspaces
hyprctl workspaces

# Execute command
hyprctl dispatch exec alacritty

# Kill window
hyprctl dispatch killactive

# Key bindings (default)
# SUPER + Q = Kill window
# SUPER + Enter = Terminal
# SUPER + D = App launcher
# SUPER + 1-9 = Switch workspace

Installation

Arch Linux

# Install Hyprland and common utilities
sudo pacman -S hyprland

# Recommended packages
sudo pacman -S \
    kitty                    # Terminal (recommended by Hyprland)
    wofi                     # App launcher
    waybar                   # Status bar
    dunst                    # Notifications
    wl-clipboard             # Clipboard
    grim slurp               # Screenshots
    swww                     # Wallpaper
    xdg-desktop-portal-hyprland

# For NVIDIA
sudo pacman -S nvidia nvidia-utils

First Run

# Start from TTY
Hyprland

# Or add to display manager
# ~/.bash_profile (startx alternative)
if [ -z "$DISPLAY" ] && [ "$XDG_VTNR" = 1 ]; then
    exec Hyprland
fi

# Default config location
~/.config/hypr/hyprland.conf

Configuration

Configuration Location

# Main config
~/.config/hypr/hyprland.conf

# Source additional configs
source = ~/.config/hypr/monitors.conf
source = ~/.config/hypr/keybinds.conf
source = ~/.config/hypr/rules.conf

# Environment file
~/.config/hypr/hyprland.conf
env = QT_QPA_PLATFORM,wayland
env = MOZ_ENABLE_WAYLAND,1

Monitor Configuration

# ~/.config/hypr/hyprland.conf

# List monitors
# hyprctl monitors

# Monitor syntax: name,resolution,position,scale
monitor = DP-1, 3840x2160@60, 0x0, 1.5
monitor = HDMI-A-1, 1920x1080@60, 2560x0, 1

# Auto-configure all monitors
monitor = , preferred, auto, 1

# Disable monitor
monitor = eDP-1, disable

# Rotate monitor
monitor = DP-1, 3840x2160@60, 0x0, 1, transform, 1
# transform: 0-7 (0=normal, 1=90°, 2=180°, 3=270°, 4-7=flipped)

# Mirror monitors
monitor = HDMI-A-1, 1920x1080@60, 0x0, 1, mirror, DP-1

Input Configuration

input {
    # Keyboard
    kb_layout = us
    kb_variant =
    kb_model =
    kb_options = caps:escape
    kb_rules =

    # Repeat rate
    repeat_rate = 50
    repeat_delay = 300

    # Mouse
    follow_mouse = 1
    sensitivity = 0
    accel_profile = flat

    # Touchpad
    touchpad {
        natural_scroll = true
        tap-to-click = true
        disable_while_typing = true
        scroll_factor = 1.0
    }
}

# Per-device configuration
device {
    name = epic-mouse-v1
    sensitivity = -0.5
}

General Settings

general {
    # Gaps and borders
    gaps_in = 5
    gaps_out = 10
    border_size = 2

    # Border colors
    col.active_border = rgba(33ccffee) rgba(00ff99ee) 45deg
    col.inactive_border = rgba(595959aa)

    # Layout
    layout = dwindle

    # Resize on border
    resize_on_border = true
}

Decoration

decoration {
    # Rounding
    rounding = 10

    # Opacity
    active_opacity = 1.0
    inactive_opacity = 0.9
    fullscreen_opacity = 1.0

    # Shadow
    drop_shadow = true
    shadow_range = 4
    shadow_render_power = 3
    col.shadow = rgba(1a1a1aee)

    # Blur
    blur {
        enabled = true
        size = 8
        passes = 2
        new_optimizations = true
        ignore_opacity = true
    }
}

Animations

animations {
    enabled = true

    # Animation curves
    bezier = myBezier, 0.05, 0.9, 0.1, 1.05
    bezier = linear, 0.0, 0.0, 1.0, 1.0

    # Animation definitions
    animation = windows, 1, 7, myBezier
    animation = windowsOut, 1, 7, default, popin 80%
    animation = border, 1, 10, default
    animation = borderangle, 1, 8, default
    animation = fade, 1, 7, default
    animation = workspaces, 1, 6, default
}

Layout Configuration

# Dwindle layout (binary tree)
dwindle {
    pseudotile = true
    preserve_split = true
    force_split = 2    # 0=follow mouse, 1=left, 2=right
}

# Master layout
master {
    new_is_master = true
    mfact = 0.55
}

# Toggle layout
bind = SUPER, SPACE, togglesplit

Key Bindings

Basic Bindings

# Syntax: bind = MODS, key, dispatcher, params

# Programs
bind = SUPER, Return, exec, kitty
bind = SUPER, D, exec, wofi --show drun
bind = SUPER, E, exec, dolphin

# Window management
bind = SUPER, Q, killactive
bind = SUPER, F, fullscreen
bind = SUPER, V, togglefloating
bind = SUPER, P, pseudo
bind = SUPER, J, togglesplit

# Exit
bind = SUPER SHIFT, M, exit

Window Focus

# Focus movement
bind = SUPER, left, movefocus, l
bind = SUPER, right, movefocus, r
bind = SUPER, up, movefocus, u
bind = SUPER, down, movefocus, d

# Vim-style movement
bind = SUPER, H, movefocus, l
bind = SUPER, L, movefocus, r
bind = SUPER, K, movefocus, u
bind = SUPER, J, movefocus, d

Window Movement

# Move window
bind = SUPER SHIFT, left, movewindow, l
bind = SUPER SHIFT, right, movewindow, r
bind = SUPER SHIFT, up, movewindow, u
bind = SUPER SHIFT, down, movewindow, d

# Vim-style
bind = SUPER SHIFT, H, movewindow, l
bind = SUPER SHIFT, L, movewindow, r
bind = SUPER SHIFT, K, movewindow, u
bind = SUPER SHIFT, J, movewindow, d

Workspace Bindings

# Switch workspace
bind = SUPER, 1, workspace, 1
bind = SUPER, 2, workspace, 2
bind = SUPER, 3, workspace, 3
bind = SUPER, 4, workspace, 4
bind = SUPER, 5, workspace, 5
bind = SUPER, 6, workspace, 6
bind = SUPER, 7, workspace, 7
bind = SUPER, 8, workspace, 8
bind = SUPER, 9, workspace, 9
bind = SUPER, 0, workspace, 10

# Move window to workspace
bind = SUPER SHIFT, 1, movetoworkspace, 1
bind = SUPER SHIFT, 2, movetoworkspace, 2
bind = SUPER SHIFT, 3, movetoworkspace, 3
bind = SUPER SHIFT, 4, movetoworkspace, 4
bind = SUPER SHIFT, 5, movetoworkspace, 5

# Move window silently (don't follow)
bind = SUPER ALT, 1, movetoworkspacesilent, 1

# Workspace scrolling
bind = SUPER, mouse_down, workspace, e+1
bind = SUPER, mouse_up, workspace, e-1

Resize Mode

# Enter resize mode
bind = SUPER, R, submap, resize

# Resize submap
submap = resize
binde = , right, resizeactive, 10 0
binde = , left, resizeactive, -10 0
binde = , up, resizeactive, 0 -10
binde = , down, resizeactive, 0 10

binde = , L, resizeactive, 10 0
binde = , H, resizeactive, -10 0
binde = , K, resizeactive, 0 -10
binde = , J, resizeactive, 0 10

# Exit resize mode
bind = , escape, submap, reset
bind = , Return, submap, reset
submap = reset

Mouse Bindings

# Move and resize with mouse
bindm = SUPER, mouse:272, movewindow       # LMB
bindm = SUPER, mouse:273, resizewindow     # RMB

# Click to focus
# (enabled by default with follow_mouse = 1)

Media Keys

# Volume (wireplumber/pamixer)
binde = , XF86AudioRaiseVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
binde = , XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
bind = , XF86AudioMute, exec, wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle
bind = , XF86AudioMicMute, exec, wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle

# Brightness (brightnessctl)
binde = , XF86MonBrightnessUp, exec, brightnessctl set 5%+
binde = , XF86MonBrightnessDown, exec, brightnessctl set 5%-

# Media player (playerctl)
bind = , XF86AudioPlay, exec, playerctl play-pause
bind = , XF86AudioPause, exec, playerctl play-pause
bind = , XF86AudioNext, exec, playerctl next
bind = , XF86AudioPrev, exec, playerctl previous

Screenshot Bindings

# Screenshot entire screen
bind = , Print, exec, grim ~/Pictures/screenshot-$(date +%Y%m%d-%H%M%S).png

# Screenshot selection
bind = SHIFT, Print, exec, grim -g "$(slurp)" ~/Pictures/screenshot-$(date +%Y%m%d-%H%M%S).png

# Screenshot to clipboard
bind = SUPER, Print, exec, grim - | wl-copy
bind = SUPER SHIFT, Print, exec, grim -g "$(slurp)" - | wl-copy

Window Rules

Rule Syntax

# windowrule = rule, window
# windowrulev2 = rule, conditions

# Window identifiers
# class: - WM_CLASS
# title: - Window title
# xwayland: - XWayland windows (0 or 1)

# List windows for class/title
# hyprctl clients

Common Rules

# Float specific windows
windowrule = float, ^(pavucontrol)$
windowrule = float, ^(nm-connection-editor)$
windowrule = float, ^(file-roller)$
windowrulev2 = float, class:^(firefox)$, title:^(Library)$

# Set workspace
windowrule = workspace 2, ^(firefox)$
windowrule = workspace 3, ^(discord)$

# Size floating windows
windowrulev2 = size 800 600, class:^(pavucontrol)$
windowrulev2 = center, class:^(pavucontrol)$

# Opacity
windowrulev2 = opacity 0.9 0.8, class:^(kitty)$

# Pin (show on all workspaces)
windowrulev2 = pin, class:^(calculator)$

# No border
windowrulev2 = noborder, class:^(wofi)$

# Fullscreen
windowrulev2 = fullscreen, class:^(mpv)$

Workspace Rules

# Assign workspaces to monitors
workspace = 1, monitor:DP-1
workspace = 2, monitor:DP-1
workspace = 3, monitor:HDMI-A-1

# Default workspace settings
workspace = 1, default:true

# Persistent workspaces
workspace = 1, persistent:true

# Special workspace (scratchpad)
bind = SUPER, S, togglespecialworkspace, magic
bind = SUPER SHIFT, S, movetoworkspace, special:magic

Autostart

Exec Commands

# exec-once runs once at startup
# exec runs on every reload

# Status bar
exec-once = waybar

# Notification daemon
exec-once = dunst

# Wallpaper
exec-once = swww init && swww img ~/wallpaper.png

# Clipboard manager
exec-once = wl-paste --watch cliphist store

# Authentication agent
exec-once = /usr/lib/polkit-kde-authentication-agent-1

# XDG portal
exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP

# Screen lock
exec-once = swayidle -w \
    timeout 300 'swaylock -f' \
    timeout 600 'hyprctl dispatch dpms off' \
    resume 'hyprctl dispatch dpms on' \
    before-sleep 'swaylock -f'

# Network manager applet
exec-once = nm-applet --indicator

# Bluetooth
exec-once = blueman-applet

hyprctl Commands

Window Management

# List windows
hyprctl clients

# Active window
hyprctl activewindow

# Kill active window
hyprctl dispatch killactive

# Move focus
hyprctl dispatch movefocus l

# Move window
hyprctl dispatch movewindow r

# Toggle floating
hyprctl dispatch togglefloating

# Fullscreen
hyprctl dispatch fullscreen 0    # Real fullscreen
hyprctl dispatch fullscreen 1    # Maximize

Workspace Commands

# List workspaces
hyprctl workspaces

# Active workspace
hyprctl activeworkspace

# Switch workspace
hyprctl dispatch workspace 5

# Move window to workspace
hyprctl dispatch movetoworkspace 3

Output Commands

# List monitors
hyprctl monitors

# Disable monitor
hyprctl keyword monitor eDP-1,disable

# Enable monitor
hyprctl keyword monitor DP-1,3840x2160@60,0x0,1.5

# DPMS control
hyprctl dispatch dpms off
hyprctl dispatch dpms on

Configuration

# Reload config
hyprctl reload

# Set configuration option
hyprctl keyword general:gaps_in 10
hyprctl keyword decoration:rounding 15

# Execute command
hyprctl dispatch exec kitty

# Get config value
hyprctl getoption general:gaps_in

Plugins

Plugin System

# Hyprland supports plugins via shared libraries

# Install hyprpm (plugin manager)
# Usually comes with hyprland-git

# List plugins
hyprpm list

# Install plugin
hyprpm add https://github.com/user/plugin

# Enable plugin
hyprpm enable plugin-name

# Update plugins
hyprpm update

Popular Plugins

# hyprspace - macOS-like overview
# hyprexpo - workspace overview
# hypr-darkwindow - dim unfocused
# hy3 - i3-like manual tiling
# hyprtrails - cursor trails

Troubleshooting

Debug Information

# Hyprland log
cat /tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log

# Current configuration
hyprctl getoption general:gaps_in

# Window info
hyprctl clients
hyprctl activewindow

# Version
hyprctl version

Common Issues

# Screen flickering (NVIDIA)
# Add to config
env = WLR_NO_HARDWARE_CURSORS,1
env = LIBVA_DRIVER_NAME,nvidia
env = GBM_BACKEND,nvidia-drm
env = __GLX_VENDOR_LIBRARY_NAME,nvidia

# Slow startup
# Check exec-once commands
# Ensure services aren't blocking

# XWayland apps blurry
# Add to windowrulev2
windowrulev2 = rounding 0, xwayland:1

# Apps not starting
# Check WAYLAND_DISPLAY
echo $WAYLAND_DISPLAY

# Keybinds not working
# Check for conflicts
# Verify syntax in config
hyprctl reload    # Watch for errors

Quick Reference

# Keybinds (defaults)
SUPER + Return          Terminal
SUPER + Q               Kill window
SUPER + D               App launcher
SUPER + 1-9             Workspace 1-9
SUPER + SHIFT + 1-9     Move to workspace
SUPER + F               Fullscreen
SUPER + V               Toggle floating
SUPER + H/J/K/L         Focus direction
SUPER + SHIFT + H/J/K/L Move window
SUPER + mouse drag      Move/resize window

# hyprctl commands
hyprctl reload                  Reload config
hyprctl clients                 List windows
hyprctl monitors                List monitors
hyprctl dispatch CMD            Execute dispatcher
hyprctl keyword OPT VAL         Set option

# Config file
~/.config/hypr/hyprland.conf

# Log file
/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log

See Also