Last Updated: 3/12/2026

Configuration Basics

Hyprland’s configuration file controls every aspect of your window manager. This guide covers the core configuration structure, essential settings, and how to organize your config effectively.

Configuration File Location

Hyprland reads its configuration from:


~/.config/hypr/hyprland.conf

Create this file if it doesn’t exist. Hyprland automatically reloads the config when you save changes — no restart needed.

Configuration Syntax

The config file uses a simple, hierarchical syntax:


# Comments start with #

# Variables
$variableName = value

# Settings blocks
blockName {
    option = value
    nested_option = value
}

# Keybindings and commands
bind = MOD, KEY, action, parameters

Including Other Files

Split your configuration across multiple files:


source = ~/.config/hypr/monitors.conf
source = ~/.config/hypr/keybindings.conf

Essential Configuration Blocks

General Settings

Controls gaps, borders, and layout:


general {
    gaps_in = 5              # Gap between windows
    gaps_out = 20            # Gap between windows and screen edge
    border_size = 2          # Window border width
    
    col.active_border = rgba(33ccffee) rgba(00ff99ee) 45deg
    col.inactive_border = rgba(595959aa)
    
    resize_on_border = false # Click borders to resize
    allow_tearing = false    # Gaming tearing support
    
    layout = dwindle         # Layout algorithm (dwindle or master)
}

Decorations

Visual effects for windows:


decoration {
    rounding = 10           # Corner rounding radius
    rounding_power = 2      # Rounding curve power
    
    active_opacity = 1.0    # Focused window opacity
    inactive_opacity = 1.0  # Unfocused window opacity
    
    shadow {
        enabled = true
        range = 4
        render_power = 3
        color = rgba(1a1a1aee)
    }
    
    blur {
        enabled = true
        size = 3
        passes = 1
        vibrancy = 0.1696
    }
}

Animations

Control animation behavior:


animations {
    enabled = yes, please :)
    
    # Define bezier curves
    bezier = easeOutQuint, 0.23, 1, 0.32, 1
    bezier = linear, 0, 0, 1, 1
    
    # Apply animations
    animation = windows, 1, 4.79, easeOutQuint
    animation = border, 1, 5.39, easeOutQuint
    animation = fade, 1, 3.03, linear
}

Input Settings

Keyboard and mouse configuration:


input {
    kb_layout = us          # Keyboard layout
    kb_variant =            # Layout variant
    kb_options =            # XKB options
    
    follow_mouse = 1        # Focus follows mouse
    sensitivity = 0         # Mouse sensitivity (-1.0 to 1.0)
    
    touchpad {
        natural_scroll = false
    }
}

Per-device configuration:


device {
    name = epic-mouse-v1
    sensitivity = -0.5
}

Monitors

Configure displays:


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

# Specific monitor config
monitor = DP-1,1920x1080@60,0x0,1
monitor = HDMI-A-1,1920x1080@60,1920x0,1

Format: monitor = NAME, RESOLUTION@RATE, POSITION, SCALE

Environment Variables

Set environment variables for the Wayland session:


env = XCURSOR_SIZE,24
env = HYPRCURSOR_SIZE,24

Layout Configuration

Dwindle Layout

Binary tree tiling (default):


dwindle {
    pseudotile = true        # Pseudotiling for non-tiling windows
    preserve_split = true    # Keep split direction
}

Master Layout

Master-stack tiling:


master {
    new_status = master      # New windows become master or slave
}

Miscellaneous Settings


misc {
    force_default_wallpaper = -1  # -1 random, 0-2 specific wallpaper
    disable_hyprland_logo = false # Disable startup logo
}

Gestures

Touchpad gestures:


gesture = 3, horizontal, workspace  # 3-finger swipe for workspace switching

Variables

Define reusable values:


$mainMod = SUPER
$terminal = kitty
$fileManager = dolphin
$menu = hyprlauncher

# Use in bindings
bind = $mainMod, Q, exec, $terminal

Color Format

Colors use RGBA hex format:


col.active_border = rgba(33ccffee)  # Blue with transparency
col.inactive_border = rgb(595959)   # Gray, fully opaque

You can also use gradients:


col.active_border = rgba(33ccffee) rgba(00ff99ee) 45deg

Configuration Tips

Start with the example config: Copy /usr/share/hypr/hyprland.conf and modify incrementally
Test changes live: Hyprland reloads on save — experiment freely
Use comments: Document your customizations
Split large configs: Use source to organize by category
Check syntax: Hyprland logs errors to stderr if config is invalid

What’s Next

Keybindings: Customize your keyboard shortcuts and workflow