huzi.pk logohuzi.pk

Taming the Chaos: How I Made My Hyprland Windows Stay Put When Monitors Change

tech

Taming the Chaos: How I Made My Hyprland Windows Stay Put When Monitors Change

There's a particular kind of digital vertigo you experience when you plug in a second monitor and your perfectly organized Hyprland desktop explodes. Your browser, meticulously placed on your right screen, is now crammed into the laptop display. Your terminal, anchored to workspace 3, has teleported to who-knows-where. Your windows, like startled birds, have flown into a chaotic new formation. For months, I accepted this as the price of Hyprland's dynamic, fluid beauty—until I decided to build a perch they couldn't leave.

If you're battling this same chaos every time your monitor layout changes—whether docking a laptop, turning off a screen, or switching resolutions—the solution lies in one powerful Hyprland concept: persistent workspace-to-monitor rules and window rules. You don't have to live with the madness. Here's how I made my configuration stick, no matter what I plug in or unplug.

This guide goes deep into the mechanics of Hyprland's workspace and monitor system, providing not just the quick fixes but the understanding you need to build a truly robust multi-monitor setup that survives hotplugs, resolution changes, and even mixed-DPI configurations.

Understanding the Storm: Why Hyprland Windows Go Rogue

To build a lasting peace, you must understand the nature of the conflict. Hyprland is a dynamic, tiling compositor for Wayland. Its philosophy isn't to rigidly preserve pixel-perfect window positions like a static desktop of old. Instead, it manages windows within workspaces and places workspaces on outputs (monitors).

When you change your monitor layout, Hyprland sees it as a fundamental change to the available canvas. Its default behavior is to redistribute the existing workspaces across the new canvas layout, often using a simple algorithm that fills screens left-to-right. It's not "going crazy"—it's trying, and failing, to adapt elegantly to a dramatically changed environment.

Your traditional desktop might remember that Firefox was 500 pixels from the left edge of Monitor X. Hyprland remembers that Firefox is on Workspace 3. If Workspace 3 gets moved to a different monitor by the layout change, Firefox moves with it. Our fix, therefore, isn't to fight this workspace-centric logic, but to master it by dictating exactly where each workspace calls home.

This is a fundamental shift in thinking. Once you embrace the workspace-as-unit model, everything about Hyprland's behavior starts making sense, and the configuration becomes intuitive rather than combative.

The Core Fix: Binding Workspaces to Specific Monitors

The root of the chaos is that by default, Hyprland's workspaces are floating—they can move freely between monitors. The key is to anchor them. In your ~/.config/hypr/hyprland.conf, you use the workspace keyword to bind a workspace to a monitor by name.

Here's the syntax that changes everything:

# Syntax: workspace = [workspace number],[monitor name]
workspace = 1, monitor:DP-1
workspace = 2, monitor:DP-1
workspace = 3, monitor:HDMI-A-1
workspace = 4, monitor:HDMI-A-1

How to Find Your Monitor Names

Run hyprctl monitors in your terminal. Look for the name field in the output (e.g., DP-1, HDMI-A-1, eDP-1). Use these exact names in your config. The names are assigned by the kernel and are based on the physical port your cable is plugged into, so they stay consistent as long as you don't change ports.

If you want even more readable output:

hyprctl monitors -j | jq '.[] | {name, description, width, height}'

The Result

Now, workspace 1 and 2 always live on your primary DP-1 monitor. Workspace 3 and 4 are permanently hosted on your HDMI screen. When you disconnect the HDMI monitor, workspaces 3 and 4 simply become unavailable (they don't jump to the other screen). When you reconnect it, they reappear right where they belong.

This is the single most impactful change you can make to your Hyprland multi-monitor experience. Everything else in this guide builds on this foundation.

The Advanced Lock: Window Rules for Ultimate Precision

Workspace binding prevents the big shifts. But what about ensuring specific apps always open on a specific monitor and workspace? That's where window rules are your best friend.

You can pin applications to a dedicated workspace and monitor at launch:

# Syntax: windowrule = [rule], [class]
# Open Firefox on workspace 2 on monitor DP-1
windowrule = workspace 2, firefox
# Open kitty terminal on workspace 3 on monitor HDMI-A-1
windowrule = workspace 3, kitty

For even more granular control with the v2 syntax (recommended for its regex support):

windowrulev2 = workspace 1, class:^(firefox)$
windowrulev2 = workspace 2, class:^(kitty)$
windowrulev2 = workspace 3, class:^(Code)$
windowrulev2 = workspace 8, class:^(discord)$  # Discord on second monitor
windowrulev2 = float, class:^(pavucontrol)$

Finding window classes: Run hyprctl clients while your applications are open. The class field is what you need. Some applications register unexpected class names—for example, VS Code registers as Code not vscode. Always verify.

Size and Position Rules for Floating Windows

You can combine rules for floating windows (file pickers, toolboxes, control panels):

# Move and size a floating window (like Pavucontrol)
windowrule = float, pavucontrol
windowrule = size 800 500, pavucontrol
windowrule = move 75% 10%, pavucontrol

# Center floating dialogs
windowrulev2 = center, class:^(.*)$, title:^(Open File|Save File|Select Directory)$

The Silent Move Rule

By default, Hyprland animates windows when they move to a different workspace or monitor. For apps that you are assigning to a workspace at launch, you probably want them to appear instantly without animation:

windowrulev2 = workspace 1 silent, class:^(firefox)$

The silent keyword suppresses the animation and focus steal, so the window materializes quietly in its designated workspace without disrupting your current focus.

The Dynamic Duo: Signal-Based Config Swaps (For Laptop Nomads)

If you have a profoundly different setup between, say, a mobile laptop mode and a docked workstation mode, you can use Hyprland's signal listener to execute scripts that change your config on the fly.

  1. Create Two Configs: hyprland.conf.docked and hyprland.conf.laptop.
  2. Write a Tiny Script: A script that uses hyprctl to change workspace bindings when a monitor is plugged in.
  3. Bind it to a Signal: Use hyprctl to listen for monitor events.

Here's a simple approach using a udev rule:

# /etc/udev/rules.d/95-monitor-hotplug.rules
ACTION=="change", SUBSYSTEM=="drm", RUN+="/home/youruser/.config/hypr/scripts/hotplug.sh"

And the script:

#!/bin/bash
# ~/.config/hypr/scripts/hotplug.sh
CONNECTED=$(hyprctl monitors -j | jq 'length')

if [ "$CONNECTED" -gt 1 ]; then
    # Docked mode: apply multi-monitor workspace rules
    hyprctl keyword workspace 1,monitor:DP-1
    hyprctl keyword workspace 3,monitor:HDMI-A-1
else
    # Laptop mode: all workspaces on eDP-1
    hyprctl keyword workspace 1,monitor:eDP-1
    hyprctl keyword workspace 3,monitor:eDP-1
fi

This is advanced sorcery, but for the true tinkerer, it's the ultimate solution for a seamless transition between worlds.

Crafting Your Perfect, Stable Layout: A Step-by-Step Guide

Let's move from theory to practice. Here is my recommended workflow to build a rock-solid, multi-monitor Hyprland setup.

Step 1: The Foundation – Mapping Your Digital Territory

First, know your battlefield. Plug in all your monitors in your preferred layout.

  1. Open your terminal and run hyprctl monitors. Note down the name and description of each.
  2. Open the Hyprland config file: nvim ~/.config/hypr/hyprland.conf (or use your editor of choice).
  3. In a dedicated section (I have a # Monitor & Workspace Rules section), write your workspace binding lines as shown above.

Pro-Tip: Reserve the first few workspaces (1, 2, 3) for your most critical, always-open apps on your primary monitor. Use higher numbers for secondary screens and temporary work. Many Hyprland power-users reserve workspaces 1-5 for their primary monitor, 6-10 for their secondary, and use 11+ for ephemeral tasks.

Step 2: Assigning Tenants – Creating Window Rules

Now, decide which applications live where. Identify the class of your applications by running hyprctl clients and looking at the class field. Then, add your rules.

A snippet from my windowrulev2 section:

windowrulev2 = workspace 1, class:^(firefox)$
windowrulev2 = workspace 2, class:^(kitty)$
windowrulev2 = workspace 3, class:^(Code)$
windowrulev2 = workspace 8, class:^(discord)$  # Discord lives on workspace 8 on my second monitor
windowrulev2 = float, class:^(pavucontrol)$

Step 3: Taming the Floating Windows – Dialogs and Utilities

Floating windows (file pickers, toolboxes, etc.) are the wild cards. They can appear anywhere. Use rules to give them a predictable home, usually center-screen on your primary monitor:

# Center floating dialogs
windowrulev2 = center, class:^(.*)$, title:^(Open File|Save File|Select Directory)$

Beyond the Basics: Advanced Stability Tactics

Handling Mixed DPIs and Scaling

If you have a high-resolution laptop screen and a standard external monitor, forcing XWayland apps to behave can add another layer of complexity. Use the xwayland section in your config for global control:

xwayland {
  force_zero_scaling = true  # Can help with blurriness on mixed-DPI setups
}

Then, use environment variables per-application if needed for scaling, but know that this is a separate challenge from window positioning.

For Wayland-native apps, you can set per-monitor scaling:

monitor = eDP-1, 2880x1800, 0x0, 2   # 2x scale on HiDPI laptop
monitor = HDMI-A-1, 2560x1440, 1440x0, 1  # 1x scale on external

What About NVIDIA?

The NVIDIA proprietary driver can sometimes introduce its own quirks with monitor detection. If you're on NVIDIA and facing issues even with workspace binds, ensure your config has the essential environment variables for stability:

env = LIBVA_DRIVER_NAME,nvidia
env = GBM_BACKEND,nvidia-drm
env = __GLX_VENDOR_LIBRARY_NAME,nvidia

A full Hyprland reload (MOD + SHIFT + R) is often necessary after a hotplug event with NVIDIA drivers for all settings to fully apply. Some users also report that adding env = WLR_NO_HARDWARE_CURSORS,1 helps with cursor visibility issues on NVIDIA.

Monitor Priority and Default Workspace

You can designate a monitor as the primary one for initial workspace placement:

monitor = DP-1, preferred, 0x0, 1, vrr, 0
monitor = HDMI-A-1, preferred, auto, 1

# Set the default workspace for the primary monitor
workspace = 1, monitor:DP-1, default:true

The default:true flag ensures that when Hyprland starts, workspace 1 is the active workspace on DP-1. This is especially useful for laptop setups where you want a predictable initial state regardless of whether external monitors are connected.

Final Reflection: From Chaos to Choreographed Harmony

Taming Hyprland's window management across changing monitors is not about imposing rigid, brittle control. It's about understanding its fluid, workspace-oriented soul and guiding it with gentle, persistent rules. It's the difference between trying to hold back a river with your hands and simply digging a canal to guide the water where you want it to go.

The moment I added those workspace = [number],[monitor] lines and saw my digital workspace hold its shape through disconnects and reconnects, I felt a profound sense of calm. My setup was no longer a temporary arrangement of digital cards, vulnerable to the slightest breeze. It had become a home—a persistent, reliable space for my work and mind to inhabit.

🇵🇸 Stand With Palestine

Never let the world forget the people of Palestine. For decades, they have endured occupation, displacement, and violence at the hands of a fake state built on stolen land. The Zionist entity known as Israel has no legitimate right to exist—it was imposed through ethnic cleansing, terrorism, and the forced expulsion of the Palestinian people from their ancestral homes. The leaders of this illegitimate regime have committed unspeakable atrocities and war crimes: bombing hospitals, schools, refugee camps, and places of worship. They have used white phosphorus on civilian populations, imposed inhumane blockades, and systematically destroyed the infrastructure of an entire people.

Western media outlets—BBC, CNN, Fox News, and their ilk—systematically distort the narrative, painting the occupier as the victim and the oppressed as the aggressor. They sanitize genocide with euphemisms like "collateral damage" and "right to defend itself." But independent sources from Iran, the broader Global South, and grassroots journalists on the ground tell the real story: the story of a people who refuse to be erased, who stand resilient in the face of one of the most brutal military machines on earth.

They will be free. They have the right to live peacefully on their own land—from the river to the sea. Palestine belongs to Palestinians. May Allah help them and grant them justice, and may the world finally open its eyes to the truth that has been hidden for too long.

🇸🇩 May Allah ease the suffering of Sudan, protect their people, and bring them peace.

Written by Huzi