hyprland.conf

The main entry point for Hyprland configuration that orchestrates the entire HyprFlux desktop environment by sourcing all other configuration files in the correct order.

Purpose

• Configuration Orchestration: Sources all modular configuration files
• Initial Setup: Executes first-time boot script
• Loading Order: Defines the sequence of configuration loading
• System Integration: Integrates with GUI tools like nwg-displays

File Location

~/.config/hypr/hyprland.conf

Configuration Structure

Initial Boot Process

# Initial boot script for first-time setup and theming
exec-once = $HOME/.config/hypr/initial-boot.sh

Purpose:

• Runs only on first boot (controlled by .initial_startup_done file)
• Sets up initial wallpapers and themes
• Applies default settings
• Initializes the desktop environment

Directory Variables

# Configuration directories
$configs = $HOME/.config/hypr/configs         # Default configurations
$UserConfigs = $HOME/.config/hypr/UserConfigs # User customizations

Benefits:

• Centralized path management
• Easy maintenance and updates
• Clear separation of system vs user configs

Configuration Loading Order

The order of sourcing is crucial for proper configuration precedence:

1. Base Keybindings

source=$configs/Keybinds.conf # Pre-configured keybinds

• Loads default system keybindings
• Provides fallback bindings if user configs fail

2. User Customizations (Priority Order)

source= $UserConfigs/Startup_Apps.conf      # Applications to start on login
source= $UserConfigs/ENVariables.conf       # Environment variables
source= $UserConfigs/Laptops.conf           # Laptop-specific settings
source= $UserConfigs/LaptopDisplay.conf     # Laptop display configuration
source= $UserConfigs/WindowRules.conf       # Window and layer rules
source= $UserConfigs/UserDecorations.conf   # Visual decorations
source= $UserConfigs/UserAnimations.conf    # Animation settings
source= $UserConfigs/UserKeybinds.conf      # Custom keybindings
source= $UserConfigs/UserSettings.conf      # Main Hyprland settings
source= $UserConfigs/01-UserDefaults.conf   # Default applications

3. Auto-Generated Configurations

# Generated by nwg-displays
source= $HOME/.config/hypr/monitors.conf    # Monitor configuration
source= $HOME/.config/hypr/workspaces.conf  # Workspace assignments

Key Features

Modular Design

• Separation of Concerns: Each aspect isolated in separate files
• Easy Maintenance: Updates don't affect user customizations
• Selective Loading: Can comment out specific configurations

User Override System

• User configs load after base configs: Ensures user preferences take precedence
• Non-destructive updates: System updates don't overwrite user settings
• Fallback mechanism: Base configs provide defaults if user configs are missing

GUI Integration

• nwg-displays compatibility: Auto-generated monitor configs are sourced
• Dynamic updates: Changes from GUI tools are automatically applied

Customization Guidelines

What NOT to Modify

# DO NOT EDIT - These ensure proper system function
exec-once = $HOME/.config/hypr/initial-boot.sh
$configs = $HOME/.config/hypr/configs
source=$configs/Keybinds.conf

Safe Modifications

Adding Custom Source Files

# Add after existing sources
source= $UserConfigs/MyCustomConfig.conf

Conditional Loading

# Load config only if file exists
source= $UserConfigs/OptionalConfig.conf

Environment-Specific Loading

# Load different configs based on hostname
source= $UserConfigs/$(hostname).conf

Advanced Customization

Custom Directory Structure

# Define custom paths
$MyConfigs = $HOME/.config/hypr/custom
source= $MyConfigs/MySettings.conf

Conditional Configuration

# Load configs based on conditions
exec-once = [[ -f "$HOME/.config/hypr/gaming.conf" ]] && source $HOME/.config/hypr/gaming.conf

Troubleshooting

Common Issues

Configuration Not Loading

# Check file exists and has correct permissions
ls -la ~/.config/hypr/UserConfigs/

# Verify syntax
hyprctl --help

Conflicting Settings

# Check loading order - later configs override earlier ones
# Move conflicting config to load last

Initial Boot Script Issues

# Check if initial boot completed
ls -la ~/.config/hypr/.initial_startup_done

# Force re-run initial boot
rm ~/.config/hypr/.initial_startup_done
hyprctl reload

Debug Commands

# Reload configuration
hyprctl reload

# Check current configuration
hyprctl getoption general:layout

# List all options
hyprctl getoption

# Monitor configuration loading
tail -f ~/.local/share/hyprland/hyprland.log

Validation

Check Configuration Syntax

# Test configuration without applying
hyprctl --help

# Validate specific settings
hyprctl getoption animations:enabled

Monitor Loading Process

# Enable debug logging
env HYPRLAND_LOG_WLR=1 hyprland

# Check which configs are being loaded
grep "source=" ~/.config/hypr/hyprland.conf

Best Practices

Configuration Management

Backup Strategy

# Backup main configuration
cp ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.backup

# Version control
cd ~/.config/hypr
git init
git add hyprland.conf
git commit -m "Initial hyprland.conf"

Documentation

# Add comments for custom modifications
# Custom modification for dual monitor setup
source= $UserConfigs/DualMonitor.conf

Update Safety

Before Updates

# Backup user configurations
tar -czf ~/hyprflux-backup-$(date +%Y%m%d).tar.gz ~/.config/hypr/UserConfigs/

After Updates

# Verify configuration still works
hyprctl reload

# Check for new features
diff ~/.config/hypr/hyprland.conf ~/.config/hypr/hyprland.conf.backup

Performance Optimization

Selective Loading

# Comment out unused configurations
# source= $UserConfigs/GamingConfig.conf  # Disabled for work setup

Lazy Loading

# Load heavy configurations only when needed
exec-once = [[ "$XDG_SESSION_TYPE" == "wayland" ]] && source $UserConfigs/WaylandSpecific.conf

Integration Examples

Multi-User Setup

# Load user-specific configurations
source= $UserConfigs/users/$(whoami).conf

Environment-Based Loading

# Different configs for different environments
case "$(hostname)" in
    "work-laptop")
        source= $UserConfigs/work.conf
        ;;
    "gaming-pc")
        source= $UserConfigs/gaming.conf
        ;;
    *)
        source= $UserConfigs/default.conf
        ;;
esac

Conditional Features

# Load gaming config only if gaming directory exists
exec-once = [[ -d "$HOME/Games" ]] && source $UserConfigs/Gaming.conf

File Dependencies

Required Files

• initial-boot.sh - Must exist for proper initialization
• configs/Keybinds.conf - Provides base keybindings
• UserConfigs/*.conf - User customization files

Optional Files

• monitors.conf - Auto-generated by nwg-displays
• workspaces.conf - Auto-generated workspace configuration

Generated Files

• .initial_startup_done - Prevents re-running initial setup
• Various cache and state files in ~/.cache/hyprland/

This main configuration file serves as the foundation of the HyprFlux system, ensuring all components load in the correct order while maintaining separation between system defaults and user customizations.