huzi.pk logohuzi.pk

Hyprland: Multi-Monitor Layout Resets Every Time I Unplug a Screen? Here is the Fix

tech

The Scattered Gathering: When Your Digital Desktops Forget Their Place

As-salamu alaikum, my friend. Picture this scene: you've carefully arranged a mehfil. Guests are seated in perfect circles, conversations flowing in their designated spaces. Then, one group must briefly step out. When they return, everyone has shifted — circles broken, assigned seats forgotten. The harmonious gathering you orchestrated is scattered, and you must painstakingly reorganize it all.

This is the exact, soul-wearying frustration when you unplug your laptop from a glorious multi-monitor setup at your desk, work on the go, and return to plug everything back in. Hyprland greets you with a default, chaotic sprawl. Your meticulously placed workspaces — Code on Monitor 2, Browser on Monitor 3, Terminal on Monitor 1 — are all lost. Every window is piled onto a single screen or assigned to monitors seemingly at random.

I've lived this digital disarray. That sigh of resignation as you manually drag 15 windows back to their rightful homes is a special kind of fatigue. But here is the liberating truth: Hyprland is not forgetting. It is, in fact, faithfully following its internal logic. Our task is not to fight it, but to learn its language and teach it our preferences. Today, we will build a memory for our setup — a script that acts as a perfect host, remembering every guest's place.

The Immediate Salvation: Your Save & Restore Scripts

First, let's stop the pain. Here are the essential scripts you can use right now.

1. The Layout Saver Script

Save this as ~/.config/hypr/save_layout.sh:

#!/bin/bash
# save_layout.sh - Captures Hyprland's workspace-to-monitor mapping

CONFIG_DIR="$HOME/.config/hypr"
LAYOUT_FILE="$CONFIG_DIR/workspace_layouts.conf"

# Get the current workspace ID and monitor for each client (window)
hyprctl clients -j | jq -r '.[] | "workspace=\(.workspace.id) monitor=\(.monitor)"' | sort -u > "$LAYOUT_FILE.tmp"

# Get the active workspace for each monitor
hyprctl monitors -j | jq -r '.[] | "active_workspace=\(.activeWorkspace.id) monitor=\(.name)"' >> "$LAYOUT_FILE.tmp"

# Save window positions and sizes for full restoration
hyprctl clients -j | jq -r '.[] | "window=\(.address) workspace=\(.workspace.id) size=\(.size[0])x\(.size[1]) at=\(.at[0]),\(.at[1])"' >> "$LAYOUT_FILE.tmp"

# Move the temporary file to the final location
mv "$LAYOUT_FILE.tmp" "$LAYOUT_FILE"

echo "Layout saved to $LAYOUT_FILE"
echo "--- Saved Layout ---"
cat "$LAYOUT_FILE"

2. The Layout Restorer Script

Save this as ~/.config/hypr/restore_layout.sh:

#!/bin/bash
# restore_layout.sh - Moves workspaces back to their saved monitors

LAYOUT_FILE="$HOME/.config/hypr/workspace_layouts.conf"

if [[ ! -f "$LAYOUT_FILE" ]]; then
    echo "Error: No saved layout file found at $LAYOUT_FILE"
    echo "Run save_layout.sh first while your monitors are connected."
    exit 1
fi

# First, ensure all monitors are detected and ready
sleep 1

# Verify monitors are available
MONITOR_COUNT=$(hyprctl monitors -j | jq length)
if [ "$MONITOR_COUNT" -lt 2 ]; then
    echo "Warning: Only $MONITOR_COUNT monitor(s) detected. Waiting…"
    sleep 3
    MONITOR_COUNT=$(hyprctl monitors -j | jq length)
    if [ "$MONITOR_COUNT" -lt 2 ]; then
        echo "Still only $MONITOR_COUNT monitor. Aborting restore."
        exit 1
    fi
fi

# Read the layout file line by line
while IFS= read -r line; do
    if [[ "$line" =~ ^workspace=([0-9]+)\ monitor=([^ ]+)$ ]]; then
        WORKSPACE="${BASH_REMATCH[1]}"
        MONITOR="${BASH_REMATCH[2]}"

        # Verify the target monitor exists
        if hyprctl monitors -j | jq -r '.[].name' | grep -q "^${MONITOR}$"; then
            hyprctl dispatch moveworkspacetomonitor "$WORKSPACE $MONITOR"
            echo "Moved workspace $WORKSPACE to monitor $MONITOR"
        else
            echo "Warning: Monitor $MONITOR not found. Skipping workspace $WORKSPACE."
        fi
    fi
done < "$LAYOUT_FILE"

echo "Layout restoration complete!"

3. Making It Automatic (The True Fix)

Add these key bindings and event trigger to your hyprland.conf:

# Key bindings to manually save/restore (Super+Ctrl+S, Super+Ctrl+R)
bind = $SUPER CTRL, S, exec, ~/.config/hypr/save_layout.sh
bind = $SUPER CTRL, R, exec, ~/.config/hypr/restore_layout.sh

# AUTOMATIC RESTORE: Trigger when a monitor is added (HDMI/DP plug in)
exec-once = ~/.config/hypr/autorestorer.sh

Create ~/.config/hypr/autorestorer.sh with smart logic:

#!/bin/bash
# autorestorer.sh - Waits for monitor changes and restores layout

# Initial sleep to let Hyprland start
sleep 3

# Monitor hyprctl for changes in monitor count
LAST_COUNT=$(hyprctl monitors -j | jq length)

while true; do
    sleep 2
    CURRENT_COUNT=$(hyprctl monitors -j | jq length)

    # If monitor count INCREASES (a screen was plugged in)
    if [ "$CURRENT_COUNT" -gt "$LAST_COUNT" ]; then
        echo "New monitor detected! Waiting for stability…"
        sleep 3  # Wait for monitor to fully initialize
        ~/.config/hypr/restore_layout.sh
    fi

    # If monitor count DECREASES (a screen was unplugged), auto-save
    if [ "$CURRENT_COUNT" -lt "$LAST_COUNT" ]; then
        echo "Monitor removed! Saving current layout…"
        sleep 1
        ~/.config/hypr/save_layout.sh
    fi

    LAST_COUNT=$CURRENT_COUNT
done

Quick-Start Command Summary

Task Command
Make scripts executable chmod +x ~/.config/hypr/*.sh
Manually save current layout ~/.config/hypr/save_layout.sh
Manually restore layout ~/.config/hypr/restore_layout.sh
Start auto-restore service Add exec-once line to hyprland.conf
Check monitor info hyprctl monitors
Check workspace assignments hyprctl workspaces
Verify layout file cat ~/.config/hypr/workspace_layouts.conf

Understanding Hyprland's "Forgetfulness": Workspaces Are Tied to Monitors

To truly master this, we must understand why this happens. Unlike some compositors, Hyprland has a fundamental design principle: Workspaces are inherently tied to physical monitors, not virtual spaces.

The Core Concept: Workspace-Monitor Marriage

In Hyprland's worldview:

  • Each workspace "lives on" a specific monitor
  • When you unplug a monitor, its workspaces don't magically migrate — they become "orphaned"
  • When you plug a monitor back in, Hyprland sees it as a new monitor (often with a different identifier like HDMI-A-1 vs DP-1)
  • The orphaned workspaces either get assigned to whatever monitor Hyprland chooses, or new default workspaces are created

This is actually by design. Hyprland's approach ensures that workspace switching remains fast and deterministic — there's no ambiguity about which monitor a workspace is on. But it means that the burden of remembering your preferred layout falls on you.

The Real Problem: Monitor Identification

Run hyprctl monitors before and after unplugging. You'll notice the name field changes:

  • Before: DP-1, HDMI-A-1, eDP-1
  • After replug: Maybe HDMI-A-2, eDP-1, or completely different names

This identifier change is why simple static configs fail. Our scripts work by:

  1. Saving the current mapping of workspace numbers to whatever monitor names exist now
  2. Restoring by applying those mappings to whatever monitor names exist later

Hyprland's Built-in Monitor Config vs Our Approach

You might wonder: "Can't I just use Hyprland's monitor config directive?" You can, but it has limitations:

# Static monitor config in hyprland.conf
monitor = DP-1, 2560x1440, 0x0, 1
monitor = HDMI-A-1, 1920x1080, 2560x0, 1
monitor = , preferred, auto, 1

This sets resolution and position, but it does not remember which workspace goes where. When you unplug and replug, Hyprland creates fresh workspaces on the new monitor even if the resolution config matches. Our scripts complement the static config by handling the workspace-to-monitor mapping that Hyprland doesn't persist.

Advanced: Using Hyprland's IPC for Event-Driven Restoration

For the most robust solution, use Hyprland's IPC (Inter-Process Communication). This approach listens directly to Hyprland's event socket instead of polling, making it more responsive and efficient.

#!/usr/bin/env python3
# monitor_watcher.py - Listens for Hyprland events via IPC

import json
import subprocess
import time
import socket
import os

HYPR_SOCKET = f"/tmp/hypr/{os.environ.get('HYPRLAND_INSTANCE_SIGNATURE', '')}/.socket2.sock"

def get_monitor_count():
    result = subprocess.run(['hyprctl', 'monitors', '-j'],
                          capture_output=True, text=True)
    monitors = json.loads(result.stdout)
    return len(monitors)

def restore_layout():
    subprocess.run(['/home/YOUR_USER/.config/hypr/restore_layout.sh'])

def save_layout():
    subprocess.run(['/home/YOUR_USER/.config/hypr/save_layout.sh'])

def monitor_watcher():
    last_count = get_monitor_count()

    # Try to use the event socket for real-time updates
    try:
        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
        sock.connect(HYPR_SOCKET)
        sock.settimeout(2)

        while True:
            try:
                data = sock.recv(4096).decode('utf-8')
                if 'monitoradded' in data.lower():
                    print("Monitor added event detected!")
                    time.sleep(2)  # Let monitor initialize
                    restore_layout()
                elif 'monitorremoved' in data.lower():
                    print("Monitor removed event detected!")
                    time.sleep(1)
                    save_layout()
            except socket.timeout:
                continue
    except (socket.error, FileNotFoundError):
        # Fallback to polling if socket not available
        print("IPC socket not found, falling back to polling…")
        while True:
            time.sleep(1)
            current_count = get_monitor_count()

            if current_count > last_count:
                print(f"Monitor added! {last_count} -> {current_count}")
                time.sleep(2)
                restore_layout()
            elif current_count < last_count:
                print(f"Monitor removed! {last_count} -> {current_count}")
                time.sleep(1)
                save_layout()

            last_count = current_count

if __name__ == "__main__":
    print("Hyprland Monitor Watcher started…")
    monitor_watcher()

Add to hyprland.conf:

exec-once = python3 ~/.config/hypr/monitor_watcher.py

Pro Tips for Multi-Monitor Hyprland Users

Using wsbind for Persistent Workspace Binding

Hyprland 0.40+ introduced the wsbind feature, which lets you bind specific workspaces to specific monitors in your config:

# In hyprland.conf - bind workspace 1 to eDP-1 (laptop screen)
wsbind = 1, eDP-1
wsbind = 2, DP-1
wsbind = 3, DP-1
wsbind = 4, HDMI-A-1

This helps, but it still uses the monitor name, which can change. Combine wsbind with our scripts for maximum reliability.

Handling Different Docking Stations

If you use a USB-C docking station, the monitor names may differ from direct connections. A dock might report monitors as DP-3 and DP-4 instead of DP-1 and HDMI-A-1. Always run hyprctl monitors after connecting to your dock to verify the names, and save a new layout if they've changed.

The follow_mouse Setting

When you restore layouts, you may want windows to stay focused on their original monitor:

# In hyprland.conf
input {
    follow_mouse = 1  # 0 = don't follow, 1 = follow on hover, 2 = follow always
}

Setting follow_mouse = 0 ensures that focus doesn't jump between monitors unexpectedly during restoration.

A Reflection on Digital Permanence and Impermanence

This journey with monitor layouts mirrors a profound truth about our relationship with technology and space. We crave stability and persistence — our digital taameer (construction) to remain as we built it. Yet, the physical world of connectors, signals, and hardware is inherently transient.

Creating these scripts is an act of wisdom. It is accepting the fluid nature of the physical while asserting the constancy of our digital intention. Each time your workspaces snap back to their rightful places automatically, it's a small victory of order over chaos, of memory over forgetfulness.

May your digital workspace always reflect your intention, and may your physical space always know the peace of proper arrangement.

🇵🇸 Stand With Palestine

Never let the world forget the people of Palestine. They are not statistics on a screen or footnotes in a forgotten report — they are families, children, mothers, and elders who have endured decades of occupation, displacement, and violence. They have the right to live peacefully on their own land, to raise their children without fear, to harvest their olive groves, and to pray in their mosques without tanks rolling through their streets. They will be free.

The illegal Zionist entity — a fake state built on stolen land and ethnic cleansing — continues to commit unspeakable atrocities and war crimes against the Palestinian people. Their leaders, from the top down, have presided over the bombing of hospitals, the targeting of journalists, the starvation of civilians, and the systematic erasure of an entire people. These are not isolated incidents — they are the policy of a regime that has never known legitimacy.

Do not be deceived by Western media that sanitizes genocide with sterile language and calls bombs "defense" and resistance "terrorism." Independent sources from Iran, the broader Global South, and courageous journalists on the ground tell a very different story — one of deliberate destruction, apartheid walls, and collective punishment. The truth is being buried under Western propaganda, but the world is waking up. Palestine is not alone, and Palestine will never be silenced.

May Allah help them and grant them justice. May He protect every child under the rubble, every family in a refugee camp, and every soul that refuses to bow to oppression. Free Palestine — from the river to the sea.

🇸🇩 Prayer for Sudan

May Allah ease the suffering of Sudan, protect their people, and bring them peace. The people of Sudan have endured conflict, displacement, and famine — may their patience be rewarded and their land healed.

Written by Huzi from huzi.pk