Hyprland Configuration Reference

hyprland.conf is the central configuration file for the Hyprland Wayland compositor. It controls everything from display output settings and which programs launch at startup, to visual effects, keybindings, and per-application window rules. This page documents every major section of the configuration used in this dotfiles setup.

Monitor setup

The monitor directive maps a physical display to a resolution, refresh rate, position, and scale factor. This setup targets a single 1080p 144 Hz display and lets Hyprland choose its position automatically.

monitor = , 1920x1080@144, auto, 1

The format is monitor = <name>, <resolution>@<hz>, <position>, <scale>. Leaving <name> empty matches any connected monitor. Setting <position> to auto lets Hyprland place the output automatically. The scale of 1 means no HiDPI scaling.

To target a specific monitor by name, replace the empty field with the connector name reported by hyprctl monitors — for example DP-1 or HDMI-A-1.

Autostart

The exec-once directive runs a command exactly once when the Hyprland session starts. The following programs are launched in order:

exec-once = nm-applet &
exec-once = waybar
exec-once = hyprpaper
exec-once = dunst
exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
exec-once = hyprctl sercursor breeze_cursors 30
exec-once = /usr/libexec/kf6/polkit-kde-authentication-agent-1
exec-once = ~/.config/hypr/scripts/check_updates.sh

nm-applet

The NetworkManager system tray applet. It runs in the background (&) and provides a GUI for managing Wi-Fi and VPN connections from the Waybar tray.

waybar

Launches the status bar. See the Waybar configuration page for details.

hyprpaper

The Hyprland wallpaper daemon. It reads hyprpaper.conf to load and apply the wallpaper to each output. The config preloads and sets /home/matias/Imágenes/wallpaper.jpg.

dunst

The notification daemon. It listens for desktop notifications and renders them according to dunstrc. See the Dunst configuration page for details.

dbus-update-activation-environment

Exports WAYLAND_DISPLAY and XDG_CURRENT_DESKTOP into the systemd user environment. This ensures D-Bus–activated services such as portals and screen-sharing tools can find the Wayland socket.

hyprctl sercursor (setcursor)

Sets the system cursor theme to breeze_cursors at size 30 so that XWayland applications inherit the correct cursor. Note: the source uses sercursor — the correct Hyprland command is setcursor. Either spelling works in most Hyprland versions but setcursor is the canonical form.

polkit-kde-authentication-agent-1

The KDE Polkit authentication agent. It displays password prompts when privileged operations (such as package installation) require administrator credentials.

check_updates.sh

A custom script that queries DNF for available package updates and sends a desktop notification if any are found. See the Update checker script section below.

Environment variables

These variables are injected into every process started by Hyprland using the env directive.

env = XCURSOR_THEME, breeze_cursors
env = XCURSOR_SIZE,24
env = HYPRCURSOR_SIZE,24
env = TZ,America/Argentina/Cordoba

Variable	Value	Purpose
`XCURSOR_THEME`	`breeze_cursors`	Sets the X11 cursor theme for XWayland apps
`XCURSOR_SIZE`	`24`	Sets the X11 cursor size in pixels
`HYPRCURSOR_SIZE`	`24`	Sets the native Hyprland cursor size in pixels
`TZ`	`America/Argentina/Cordoba`	Sets the system timezone used by the clock and any timezone-aware applications

Look and feel

General

general {
    gaps_in = 5
    gaps_out = 5
    border_size = 1
    col.active_border = rgba(33ccffee) rgba(00ff99ee) 45deg
    col.inactive_border = rgba(595959aa)
    resize_on_border = false
    allow_tearing = false
    layout = dwindle
}

gaps_in and gaps_out both sit at 5 pixels, creating a uniform gap between windows and between windows and the screen edge. The active border is a 45-degree gradient from cyan to green. The default tiling layout is dwindle.

Decoration

decoration {
    rounding = 10
    active_opacity = 1.0
    inactive_opacity = 1.0

    shadow {
        enabled = true
        range = 4
        render_power = 3
        color = rgba(1a111ee0)
    }
    blur {
        enabled = true
        size = 3
        passes = 1
        vibrancy = 0.1696
    }
}

Windows have 10-pixel rounded corners. Both focused and unfocused windows are fully opaque. Drop shadows are enabled with a short range (4 px) and a dark purple tint (rgba(1a111ee0)). Background blur is enabled with a single pass and a size of 3.

Animations

animations {
    enabled = yes, please :)

    bezier = easeOutQuint,   0.23, 1,    0.32, 1
    bezier = easeInOutCubic, 0.65, 0.05, 0.36, 1
    bezier = linear,         0,    0,    1,    1
    bezier = almostLinear,   0.5,  0.5,  0.75, 1
    bezier = quick,          0.15, 0,    0.1,  1

    animation = global,        1,  10,   default
    animation = border,        1,  5.39, easeOutQuint
    animation = windows,       1,  4.79, easeOutQuint
    animation = windowsIn,     1,  4.1,  easeOutQuint, popin 87%
    animation = windowsOut,    1,  1.49, linear,       popin 87%
    animation = workspaces,    1,  1.94, almostLinear, fade
    animation = workspacesIn,  1,  1.21, almostLinear, fade
    animation = workspacesOut, 1,  1.94, almostLinear, fade
}

Five custom bezier curves drive the animations. Windows pop in and out at 87% of their final size using the popin style. Workspace transitions use a near-linear fade so they feel fast without being jarring.

Input

input {
    kb_layout = latam
    follow_mouse = 1
    sensitivity = 0

    touchpad {
        natural_scroll = false
    }
}

The keyboard layout is set to latam (Latin American Spanish). Mouse sensitivity is left at 0 — no acceleration or deceleration is applied. Touchpad natural scrolling is disabled so the scroll direction matches traditional behavior. A 3-finger horizontal gesture is mapped to workspace switching:

gesture = 3, horizontal, workspace

To change the keyboard layout, replace latam with your locale code (e.g. us, gb, de). You can also set kb_variant for regional variants such as intl for US International.

Keybindings

$mainMod is set to SUPER (the Windows/Meta key). The table below lists every binding defined in hyprland.conf.

Keybind	Action
`Super + Q`	Open Kitty terminal
`Super + C`	Close active window
`Super + M`	Exit the Hyprland session (`exit,` dispatcher)
`Super + E`	Open Dolphin file manager
`Super + V`	Toggle floating for active window
`Super + R`	Open Wofi launcher (`wofi --show drun`)
`Super + P`	Toggle pseudotiling
`Super + J`	Toggle split direction
`Super + B`	Reload Waybar
`Super + F`	Toggle fullscreen
`Super + N`	Close latest notification
`Super + H`	Pop notification from history
`Super + Shift + N`	Close all notifications
`Print`	Screenshot region → Swappy
`Shift + Print`	Screenshot full screen → Swappy
`Super + Arrow keys`	Move window focus
`Super + 1–0`	Switch to workspace 1–10
`Super + Shift + 1–0`	Move window to workspace 1–10
`Super + S`	Toggle scratchpad workspace
`XF86AudioRaiseVolume`	Volume +5%
`XF86AudioLowerVolume`	Volume −5%
`XF86AudioMute`	Toggle mute
`XF86MonBrightnessUp/Down`	Brightness ±5%
`XF86AudioNext/Prev/Play/Pause`	Media controls via playerctl

Window rules

Window rules apply floating, centering, and sizing constraints to specific applications by matching their Wayland class name.

# Suppress maximize requests from all apps
windowrule = suppressevent maximize, class:.*

# Fix XWayland drag issues
windowrule = nofocus,class:^$,title:^$,xwayland:1,floating:1,fullscreen:0,pinned:0

# KDE Plasma System Monitor
windowrulev2 = float,  class:^(org.kde.plasma-systemmonitor)$
windowrulev2 = center, class:^(org.kde.plasma-systemmonitor)$
windowrulev2 = size 1100 700, class:^(org.kde.plasma-systemmonitor)$

# Okular PDF viewer
windowrulev2 = float,  class:^(org.kde.okular)$
windowrulev2 = size 1000 800, class:^(org.kde.okular)$

# PulseAudio Volume Control
windowrulev2 = float,  class:^(org.pulseaudio.pavucontrol)$
windowrulev2 = center, class:^(org.pulseaudio.pavucontrol)$
windowrulev2 = size 1000 800, class:^(org.pulseaudio.pavucontrol)$

# Prism Launcher
windowrulev2 = float,  class:^(org.prismlauncher.PrismLauncher)$
windowrulev2 = center, class:^(org.prismlauncher.PrismLauncher)$
windowrulev2 = size 1000 800, class:^(org.prismlauncher.PrismLauncher)$

# NetworkManager Connection Editor
windowrulev2 = float,  class:^(nm-connection-editor)$
windowrulev2 = center, class:^(nm-connection-editor)$
windowrulev2 = size 1000 800, class:^(nm-connection-editor)$

# Dolphin file manager
windowrulev2 = float,  class:^(org.kde.dolphin)$
windowrulev2 = center, class:^(org.kde.dolphin)$
windowrulev2 = size 1000 800, class:^(org.kde.dolphin)$

# KCalc
windowrulev2 = float,  class:^(org.kde.kcalc)$
windowrulev2 = center, class:^(org.kde.kcalc)$
windowrulev2 = size 600 600, class:^(org.kde.kcalc)$

# CurseForge
windowrulev2 = float,  class:^(CurseForge)$
windowrulev2 = center, class:^(CurseForge)$
windowrulev2 = size 1000 800, class:^(CurseForge)$

Each floating app is centered on screen and given a fixed initial size. This keeps utility windows from covering the entire display while still allowing you to resize them manually.

Update checker script

The script at ~/.config/hypr/scripts/check_updates.sh runs at login, queries DNF for available updates, and sends a desktop notification if any packages are pending.

#!/bin/bash

# Verificar actualizaciones (solo descarga metadatos)
updates=$(dnf check-update -q | grep -c '^\S')

if [ "$updates" -gt 0 ]; then
  notify-send "Actualizaciones disponibles" \
    "Hay $updates paquetes listos para actualizar en Fedora." \
    -i software-update-available
fi

dnf check-update -q fetches metadata without printing progress output. The result is piped through grep -c '^\S' to count lines that start with a non-whitespace character (package entries). If the count is greater than zero, notify-send dispatches a notification that Dunst will display.

dnf check-update exits with code 100 when updates are available and 0 when the system is up to date. The script counts output lines rather than checking the exit code, which is equally reliable for this purpose.

Get Started

Configuration

Guides

Monitor setup

Autostart

Environment variables

Look and feel

General

Decoration

Animations

Input

Keybindings

Window rules

Update checker script

Build docs developers (and LLMs) love

Get Started

Configuration

Guides

Documentation Index

​Monitor setup

​Autostart

​Environment variables

​Look and feel

​General

​Decoration

​Animations

​Input

​Keybindings

​Window rules

​Update checker script

Build docs developers (and LLMs) love

Monitor setup

Autostart

Environment variables

Look and feel

General

Decoration

Animations

Input

Keybindings

Window rules

Update checker script