Workspaces bound to a monitor pile onto the wrong screen and never go back after docking
The behaviour described is real and the fix is mechanically sound. hl.workspace_rule accepts monitor, default and persistent per the wiki. The Monitor param for dispatchers explicitly accepts desc: and a description. hl.dsp.workspace.move({ workspace?, monitor }) and hl.dsp.workspace.swap_monitors({ monitor1, monitor2 }) are both documented. The socat -U - UNIX-CONNECT:$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock | while read -r line pattern and the monitoradded event are copied correctly from the IPC page's own bash example. hyprctl dispatch 'hl.dsp....' is a real invocation form (Omarchy's own omarchy-hyprland-monitor-clamshell uses hyprctl dispatch "hl.dsp.dpms({ action = \"$action\", monitor = \"$INTERNAL\" })"). o.launch_on_start is real (default/hypr/helpers.lua:118), and socat is in extra so pacman -S --needed socat is correct and the Omarchy ALPM guard only blocks -S combined with -u. Two citation errors in the cause, though. (1) #7049 is **closed as not_planned**, not "still open". (2) The #5464 characterisation is wrong: the reporter did *not* find connector names shifting between boots. A commenter merely remarked in passing that "ports changing is normal". The reporter's problem persisted after switching to desc: and the thread ended on a config syntax error (default=true instead of default:true), with vaxerski closing it as part of the issues→discussions migration. A reader who trusts "the rules were matching nothing" as the documented root cause is being misled about what that ticket shows.
hl.dsp.workspace.move will happily move a workspace to a monitor that is disabled or mirrored, which hides its windows. Guard the script against firing while only one monitor exists (the monitoradded trigger already does this in practice, but a manual run undocked will pile everything onto the laptop panel).
Symptom
I pin workspaces 1-5 to the external DP-1 and 6-10 to the laptop panel. If I boot or log in undocked, every workspace is created on the laptop screen. Then I dock, the external monitor lights up, and workspaces 1-5 stay on the laptop. They never migrate back. Same thing after a monitor sleeps and wakes. Persistent workspaces also stop being persistent, and after a reboot my monitors sometimes come back as DP-2/HDMI-A-3 instead of DP-1/HDMI-A-1, so the rules don't match at all any more.
Cause
A workspace rule's monitor field is applied when the workspace is *created*, not continuously. If the named output does not exist at that moment, Hyprland creates the workspace on whatever monitor is available, and nothing moves it later when the output appears. There is no rule condition that matches monitor state: the feature request for one, hyprwm/Hyprland #7049 ("Window/Workspace Rules to Match Monitors States"), was closed as *not planned*, so this is settled behaviour rather than a pending fix. Connector names are a separate, compounding hazard. DRM connector numbering is not stable across boots or across cable/port changes, so a rule pinned to DP-1 can silently match nothing after a reboot. This is why the wiki documents the desc: prefix. (Hyprland #5464 is the frequently-cited report of workspaces landing on the wrong screen, but note it was closed as not-planned during the issues→discussions migration and the reporter's specific case turned out to involve a config syntax error, so treat it as a symptom report rather than a root-cause analysis.)
Fix
Steps 1-3 are correct as written. Keep the desc: monitor rules, the hypr-restore-workspaces socat listener, and the one-shot hl.dsp.workspace.move repair. Three refinements:
**Trim the duplicate rules in Step 1.** The loop already emits a rule for workspaces 1 and 6, and the two default = true lines below re-declare them. Merge instead, so there is exactly one rule per workspace and exactly one default per monitor:
for i = 1, 5 do
hl.workspace_rule({ workspace = tostring(i), monitor = EXT, persistent = true, default = (i == 1) })
end
for i = 6, 10 do
hl.workspace_rule({ workspace = tostring(i), monitor = LAP, persistent = true, default = (i == 6) })
end
**Verify the description string round-trips before relying on it.** A desc: value with a typo fails silently exactly like a stale connector name:
hyprctl monitors -j | jq -r '.[] | "\(.name)\t\(.description)"'
hyprctl dispatch 'hl.dsp.focus({ monitor = "desc:Dell Inc. DELL U2723QE 8CJ3XX3" })'
If focus does not move, the string is wrong. Remember to drop the trailing (DP-1).
**Also handle monitorremoved.** The listener only re-homes on monitoradded, so a monitor that sleeps and wakes without emitting an add event leaves workspaces stranded. Widen the case:
handle() {
case $1 in
monitoradded*|monitorremoved*) sleep 1; restore ;;
esac
}
Verify
Undock, log in, dock again. hyprctl workspaces -j | jq -r '.[] | "\(.id) -> \(.monitor)"' should show workspaces 1-5 on the external and 6-10 on the laptop within a second or two of the monitor coming up.
Sources
- https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/Configuring/Basics/Workspace-Rules.md
- https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/Configuring/Basics/Dispatchers.md
- https://raw.githubusercontent.com/hyprwm/hyprland-wiki/main/content/IPC/_index.md
- https://github.com/hyprwm/Hyprland/issues/5464
- https://github.com/hyprwm/Hyprland/issues/7049
- https://wiki.hypr.land/Configuring/Basics/Workspace-Rules/