H
HyprL

Monitor Setup & Display Configuration

Table of Contents

HyprL provides comprehensive monitor configuration options to support single displays, multi-monitor setups, high refresh rates, different resolutions, and custom scaling. This guide covers everything from basic setup to advanced display configurations.

Quick Start

Automatic Detection

HyprL automatically detects your monitors on startup. For most users, the default configuration works out of the box:

# Check current monitor configuration
hyprctl monitors

# Apply automatic configuration
hyprL config monitors auto

Manual Configuration

For custom setups, use the interactive monitor configurator:

hyprL config monitors

Monitor Configuration Files

HyprL organizes monitor configurations in ~/.config/hypr/conf/monitors/:

monitors/
├── default.conf          # Automatic detection
├── 1920x1080.conf       # Full HD setup
├── 2560x1440.conf       # QHD setup
├── 2560x1440@120x125.conf   # High refresh rate
├── 3440x1440.conf       # Ultrawide setup
├── highres.conf         # 4K and higher
└── nwg-displays.conf    # GUI tool configuration

Basic Monitor Setup

Single Monitor Configuration

# ~/.config/hypr/conf/monitors/1920x1080.conf
monitor = DP-1, 1920x1080@60, 0x0, 1

# Monitor syntax: NAME, RESOLUTION@REFRESH, POSITION, SCALE

Common Resolutions

# Full HD (1080p)
monitor = DP-1, 1920x1080@60, 0x0, 1

# QHD (1440p)
monitor = DP-1, 2560x1440@60, 0x0, 1

# 4K (2160p)
monitor = DP-1, 3840x2160@60, 0x0, 1.5

# Ultrawide QHD
monitor = DP-1, 3440x1440@60, 0x0, 1

# Laptop displays
monitor = eDP-1, 1366x768@60, 0x0, 1

Multi-Monitor Setup

Dual Monitor Configuration

# Primary monitor (left)
monitor = DP-1, 2560x1440@144, 0x0, 1

# Secondary monitor (right)
monitor = HDMI-A-1, 1920x1080@60, 2560x0, 1

# Workspace assignments
workspace = 1, monitor:DP-1
workspace = 2, monitor:DP-1
workspace = 3, monitor:HDMI-A-1
workspace = 4, monitor:HDMI-A-1

Triple Monitor Setup

# Left monitor
monitor = DP-2, 1920x1080@60, 0x0, 1

# Center monitor (primary)
monitor = DP-1, 2560x1440@144, 1920x0, 1

# Right monitor
monitor = HDMI-A-1, 1920x1080@60, 4480x0, 1

# Workspace distribution
workspace = 1, monitor:DP-2
workspace = 2, monitor:DP-2
workspace = 3, monitor:DP-1, default:true
workspace = 4, monitor:DP-1
workspace = 5, monitor:HDMI-A-1
workspace = 6, monitor:HDMI-A-1

Vertical Monitor Setup

# Horizontal primary
monitor = DP-1, 2560x1440@144, 0x0, 1

# Vertical secondary (rotated)
monitor = DP-2, 1920x1080@60, 2560x0, 1, transform, 1

# Transform values:
# 0 - normal
# 1 - 90° clockwise
# 2 - 180°
# 3 - 270° clockwise (90° counter-clockwise)

High Refresh Rate Setup

Gaming Configurations

# High refresh rate gaming
monitor = DP-1, 2560x1440@165, 0x0, 1
monitor = DP-1, 1920x1080@240, 0x0, 1

# Variable refresh rate (FreeSync/G-Sync)
monitor = DP-1, 2560x1440@144, 0x0, 1, vrr, 1

# Adaptive sync
misc {
    vrr = 1
    vfr = true
}

Mixed Refresh Rates

# Gaming monitor
monitor = DP-1, 2560x1440@144, 0x0, 1, vrr, 1

# Secondary monitor
monitor = HDMI-A-1, 1920x1080@60, 2560x0, 1

# Per-monitor workspace rules
windowrule = workspace 1, ^(steam)$
windowrule = workspace 1, ^(lutris)$
windowrule = workspace 3, ^(firefox)$

Scaling and DPI

HiDPI Configuration

# 4K monitor with 150% scaling
monitor = DP-1, 3840x2160@60, 0x0, 1.5

# Mixed DPI setup
monitor = eDP-1, 1920x1080@60, 0x0, 1     # Laptop screen
monitor = DP-1, 3840x2160@60, 1920x0, 2   # 4K external (200% scale)

# Per-monitor scaling
xwayland {
    force_zero_scaling = true
}

Fractional Scaling

# Fractional scaling examples
monitor = DP-1, 2560x1440@60, 0x0, 1.25   # 125%
monitor = DP-1, 3840x2160@60, 0x0, 1.75    # 175%

# Enable fractional scaling
misc {
    allow_session_lock_restore = true
    fractional_scaling_algorithm = "lanczos"
}

Advanced Monitor Features

Custom Refresh Rates

# Custom refresh rate
monitor = DP-1, 2560x1440@165.02, 0x0, 1

# Multiple refresh rate options
monitor = DP-1, preferred, auto, 1  # Use preferred mode
monitor = DP-1, highres, auto, 1    # Highest resolution
monitor = DP-1, highrr, auto, 1     # Highest refresh rate

Monitor Positioning

# Complex positioning
monitor = DP-1, 2560x1440@144, 0x0, 1      # Primary at origin
monitor = DP-2, 1920x1080@60, -1920x0, 1   # Left of primary
monitor = DP-3, 1920x1080@60, 2560x0, 1    # Right of primary
monitor = HDMI-A-1, 1920x1080@60, 0x-1080, 1  # Above primary

# Align monitors by center
monitor = DP-1, 2560x1440@144, 0x0, 1
monitor = DP-2, 1920x1080@60, 2560x180, 1  # Vertically centered

Configuration Tools

GUI Configuration

# Install nwg-displays
sudo pacman -S nwg-displays

# Launch GUI configurator
nwg-displays

# Apply generated configuration
hyprL config monitors load nwg-displays

Command Line Tools

# HyprL monitor manager
hyprL config monitors                    # Interactive setup
hyprL config monitors list              # List available monitors
hyprL config monitors detect            # Auto-detect setup
hyprL config monitors preset <name>     # Apply preset
hyprL config monitors backup            # Backup current config
hyprL config monitors restore           # Restore backup

# Hyprland native commands
hyprctl monitors                        # List current monitors
hyprctl keyword monitor "DP-1,1920x1080@60,0x0,1"  # Set monitor
hyprctl reload                          # Reload configuration

Workspace Management

Monitor-Specific Workspaces

# Assign workspaces to monitors
workspace = 1, monitor:DP-1, default:true
workspace = 2, monitor:DP-1
workspace = 3, monitor:DP-1
workspace = 4, monitor:HDMI-A-1, default:true
workspace = 5, monitor:HDMI-A-1
workspace = 6, monitor:HDMI-A-1

# Workspace switching keybinds
bind = $mainMod, 1, workspace, 1
bind = $mainMod, 2, workspace, 2
bind = $mainMod, 3, workspace, 3
bind = $mainMod, 4, workspace, 4

# Move windows between monitors
bind = $mainMod SHIFT, 1, movetoworkspace, 1
bind = $mainMod SHIFT, 2, movetoworkspace, 2

Dynamic Workspace Assignment

# Smart workspace distribution
workspace = 1, monitor:DP-1
workspace = 2, monitor:DP-1  
workspace = 3, monitor:DP-1
workspace = 4, monitor:HDMI-A-1
workspace = 5, monitor:HDMI-A-1
workspace = 6, monitor:HDMI-A-1

# Auto-move applications
windowrule = workspace 1, ^(kitty)$
windowrule = workspace 3, ^(firefox)$
windowrule = workspace 4, ^(discord)$
windowrule = workspace 5, ^(spotify)$

Monitor Profiles

Gaming Profile

# ~/.config/hypr/conf/monitors/gaming.conf
monitor = DP-1, 2560x1440@165, 0x0, 1, vrr, 1
monitor = HDMI-A-1, 1920x1080@60, 2560x180, 1

# Gaming-optimized settings
decoration {
    rounding = 0
    blur = false
}

animations {
    enabled = false
}

misc {
    vrr = 1
    vfr = true
    no_direct_scanout = false
}

Productivity Profile

# ~/.config/hypr/conf/monitors/productivity.conf
monitor = DP-1, 2560x1440@60, 0x0, 1
monitor = DP-2, 1920x1080@60, 2560x180, 1
monitor = HDMI-A-1, 1920x1080@60, 0x-1080, 1, transform, 1

# Productivity settings
workspace = 1, monitor:DP-1     # Main workspace
workspace = 2, monitor:DP-2     # Communication
workspace = 3, monitor:HDMI-A-1 # Reference/docs

Presentation Profile

# ~/.config/hypr/conf/monitors/presentation.conf
monitor = eDP-1, 1920x1080@60, 0x0, 1      # Laptop screen
monitor = HDMI-A-1, 1920x1080@60, 0x0, 1, mirror, eDP-1  # Mirrored

# Presentation optimizations
decoration {
    blur = false
    drop_shadow = false
}

misc {
    disable_hyprland_logo = true
    disable_splash_rendering = true
}

Troubleshooting

Common Issues

Monitor Not Detected

# Check connected monitors
hyprctl monitors all
lsmod | grep amdgpu  # AMD GPU
lsmod | grep nvidia  # NVIDIA GPU
lsmod | grep i915    # Intel iGPU

# Force monitor detection
hyprctl reload
sudo systemctl restart display-manager

Incorrect Resolution

# Check available modes
xrandr  # If available
hyprctl monitors all

# Force specific mode
monitor = DP-1, 2560x1440@144, 0x0, 1
monitor = DP-1, preferred, auto, 1  # Use preferred mode

Scaling Issues

# Fix fractional scaling
misc {
    allow_session_lock_restore = true
}

# XWayland scaling
xwayland {
    force_zero_scaling = true
}

# Per-app scaling
windowrule = size 1920 1080, ^(steam)$

Multi-Monitor Positioning

# Debug positioning
hyprctl monitors

# Reset positioning
monitor = DP-1, 2560x1440@144, 0x0, 1
monitor = HDMI-A-1, 1920x1080@60, auto, 1  # Auto-position

Advanced Troubleshooting

Display Driver Issues

# Check graphics drivers
lspci -k | grep -A 2 -i "VGA\|3D\|Display"

# NVIDIA specific
nvidia-smi
cat /proc/driver/nvidia/version

# AMD specific
lspci -k | grep -A 3 -i amd

Performance Issues

# Monitor performance
hyprctl monitors all
hyprctl systeminfo

# Disable problem features
decoration {
    blur = false
}

animations {
    enabled = false
}

Configuration Examples

Complete Multi-Monitor Setup

# ~/.config/hypr/conf/monitors/workstation.conf

# Monitor configuration
monitor = DP-1, 2560x1440@144, 1920x0, 1    # Primary center
monitor = DP-2, 1920x1080@60, 0x180, 1      # Secondary left
monitor = HDMI-A-1, 1920x1080@60, 4480x180, 1  # Secondary right

# Workspace assignments
workspace = 1, monitor:DP-1, default:true   # Main development
workspace = 2, monitor:DP-1                 # Secondary development  
workspace = 3, monitor:DP-1                 # Testing
workspace = 4, monitor:DP-2, default:true  # Communication
workspace = 5, monitor:DP-2                 # Music/media
workspace = 6, monitor:HDMI-A-1, default:true  # Reference/docs
workspace = 7, monitor:HDMI-A-1            # Monitoring

# Window rules
windowrule = workspace 1, ^(code)$
windowrule = workspace 1, ^(kitty)$
windowrule = workspace 4, ^(discord)$
windowrule = workspace 4, ^(slack)$
windowrule = workspace 5, ^(spotify)$
windowrule = workspace 6, ^(firefox)$
windowrule = workspace 7, ^(htop)$

Best Practices

Performance Optimization

  1. Use appropriate refresh rates: Don’t use high refresh rates unnecessarily
  2. Optimize scaling: Use integer scaling when possible
  3. Disable unused features: Turn off blur/animations for secondary monitors
  4. Match refresh rates: Use similar refresh rates for smoother experience

Multi-Monitor Workflow

  1. Logical workspace distribution: Group related workspaces on same monitor
  2. Primary monitor placement: Put main work on highest quality monitor
  3. Consistent positioning: Keep monitor arrangement consistent with physical setup
  4. Application-specific rules: Auto-assign apps to appropriate monitors

Hardware Considerations

  1. Cable quality: Use high-quality DisplayPort/HDMI cables for high refresh rates
  2. GPU limitations: Check maximum supported resolution/refresh rate combinations
  3. Monitor capabilities: Verify monitor supports desired resolution/refresh rate
  4. Power management: Configure proper power saving for external monitors

This comprehensive monitor setup guide covers everything from basic single-monitor configurations to complex multi-monitor workstations, ensuring optimal display configuration for any HyprL setup.