Note: This article has been superseded by Moving Hyprland Workspaces to the Next Monitor (Lua Config Edition), which covers the updated script for Hyprland's Lua-based configuration.

Introduction

Aerospace is a tiling window manager for MacOS. One of its handy features is move-workspace-to-monitor --wrap-around next, which moves the current workspace to the next monitor and wraps around when reaching the last one.

This guide (more like me dumping this script on the internet) shows you how to replicate this behavior in Hyprland, a dynamic tiling Wayland compositor.

Prerequisites

• Hyprland - includes hyprctl by default
• jq - JSON processor used to parse hyprctl output

The Script

Add this script somewhere on your system, and make it executable.

#!/usr/bin/env bash

ACTIVE_WS_JSON=$(hyprctl activeworkspace -j)

WS_ID=$(echo "$ACTIVE_WS_JSON" | jq -r '.id')
CURRENT_MON=$(echo "$ACTIVE_WS_JSON" | jq -r '.monitor')

# read lines and put in array MONITORS
mapfile -t MONITORS < <(hyprctl monitors -j | jq -r '.[].name')

for i in "${!MONITORS[@]}"; do
  if [[ "${MONITORS[$i]}" == "$CURRENT_MON" ]]; then
    CURRENT_INDEX=$i
    break
  fi
done

NEXT_INDEX=$(( (CURRENT_INDEX + 1) % ${#MONITORS[@]} ))
NEXT_MON="${MONITORS[$NEXT_INDEX]}"

hyprctl dispatch moveworkspacetomonitor "$WS_ID" "$NEXT_MON"

How It Works

1. Get active workspace info: hyprctl activeworkspace -j returns JSON with the current workspace ID and monitor name
2. Extract workspace ID and monitor: jq parses the JSON to get .id and .monitor
3. Build monitor list: hyprctl monitors -j returns all connected monitors, which we store in an array
4. Find current monitor index: Loop through the array to find where the current monitor is positioned
5. Calculate next monitor: Using modulo arithmetic (current + 1) % total gives us the next index, wrapping around to 0 when at the end
6. Move workspace: hyprctl dispatch moveworkspacetomonitor moves the workspace to the target monitor

Keybinding

Then bind it to a keyboard shortcut:

$mainMod = ALT # Sets "ALT" key as main modifier
bind = $mainMod SHIFT, TAB, exec, <SCRIPT_FOLDER>/move_workspace_to_next_monitor.sh

# now ALT + SHIFT + TAB will move your current workspace to the next screen.