Skip to Content
reference-yysui1kWorkspace Management

Last Updated: 3/12/2026

Workspace Management

Hyprland provides fully dynamic workspaces that are created and destroyed on demand. This guide covers workspace navigation, window movement, special workspaces (scratchpads), and workspace rules.

Dynamic Workspaces

Unlike traditional desktop environments with fixed workspace counts, Hyprland creates workspaces dynamically:

  • Workspaces are created when you switch to them or move a window to them
  • Empty workspaces are automatically destroyed
  • No need to pre-configure workspace count

Switching Workspaces

By Number

bind = $mainMod, 1, workspace, 1
bind = $mainMod, 2, workspace, 2
bind = $mainMod, 3, workspace, 3
# ... through 10

Relative Navigation

bind = $mainMod, mouse_down, workspace, e+1  # Next workspace
bind = $mainMod, mouse_up, workspace, e-1    # Previous workspace

The e+1 and e-1 syntax means “relative to current workspace.”

Via hyprctl

hyprctl dispatch workspace 5
hyprctl dispatch workspace e+1
hyprctl dispatch workspace e-1

Moving Windows Between Workspaces

Move and Follow

bind = $mainMod SHIFT, 1, movetoworkspace, 1
bind = $mainMod SHIFT, 2, movetoworkspace, 2
# ... through 10

This moves the active window to the specified workspace and switches to that workspace.

Move Silently (Stay on Current Workspace)

bind = $mainMod CTRL, 1, movetoworkspacesilent, 1

Or via hyprctl:

hyprctl dispatch movetoworkspacesilent 3

Special Workspaces (Scratchpads)

Special workspaces are hidden workspaces that can be toggled on/off, useful for dropdown terminals or quick-access apps.

Creating a Special Workspace

# Toggle special workspace named "magic"
bind = $mainMod, S, togglespecialworkspace, magic

# Move window to special workspace
bind = $mainMod SHIFT, S, movetoworkspace, special:magic

Multiple Special Workspaces

You can have multiple named special workspaces:

bind = $mainMod, T, togglespecialworkspace, terminal
bind = $mainMod, N, togglespecialworkspace, notes
bind = $mainMod, M, togglespecialworkspace, music

Via hyprctl

hyprctl dispatch togglespecialworkspace magic
hyprctl dispatch movetoworkspace special:terminal

Workspace Rules

Customize workspace behavior with workspace rules:

Disable Gaps on Specific Workspaces

workspace = w[tv1], gapsout:0, gapsin:0
workspace = f[1], gapsout:0, gapsin:0

Combined with window rules for a true fullscreen experience:

windowrule {
    name = no-gaps-fullscreen
    match:workspace = f[1]
    match:float = false
    
    border_size = 0
    rounding = 0
}

Persistent Workspaces

By default, empty workspaces are destroyed. To keep specific workspaces persistent:

workspace = 1, persistent:true
workspace = 2, persistent:true

Default Workspace for Monitors

Assign default workspaces to monitors:

workspace = 1, monitor:DP-1, default:true
workspace = 2, monitor:HDMI-A-1, default:true

Querying Workspaces

List All Workspaces

hyprctl workspaces

Returns workspace IDs, window counts, and monitor assignments.

Get Active Workspace

hyprctl activeworkspace

In JSON Format

hyprctl workspaces -j
hyprctl activeworkspace -j

Multi-Monitor Workspace Behavior

Hyprland assigns workspaces independently per monitor:

  • Each monitor can have its own active workspace
  • Switching workspaces on one monitor doesn’t affect others
  • Windows can be moved between monitors via workspace assignment

Move Window to Different Monitor

# Move to workspace 5 (which may be on another monitor)
hyprctl dispatch movetoworkspace 5

Workspace Naming

Workspaces can have custom names:

workspace = 1, name:web
workspace = 2, name:code
workspace = 3, name:terminal

Switch by name:

hyprctl dispatch workspace name:web

Advanced Workspace Navigation

Cycle Through Occupied Workspaces

bind = $mainMod, Tab, workspace, m+1   # Next occupied workspace
bind = $mainMod SHIFT, Tab, workspace, m-1  # Previous occupied workspace

Jump to First/Last Workspace

bind = $mainMod, Home, workspace, 1
bind = $mainMod, End, workspace, 10

Workspace Tips

  1. Use special workspaces for quick-access apps: Dropdown terminal, music player, notes
  2. Assign apps to specific workspaces: Use window rules to send browsers to workspace 2, terminals to 3, etc.
  3. Disable gaps for media workspaces: Create immersive fullscreen experiences
  4. Name workspaces semantically: “web”, “code”, “comm” instead of numbers
  5. Use relative navigation: e+1/e-1 for fluid workspace switching

What’s Next

Explore advanced visual customization with the Animations guide.

Environment VariablesMonitors