Hyprland exposes 2 UNIX Sockets, for controlling / getting info about Hyprland via code / bash utilities.

Hyprland Instance Signature (HIS)



Used for hyprctl-like requests. See the Hyprctl page for commands.

basically, write [flag(s)]/command args.


Used for events. Hyprland will write to each connected client live events like this:

EVENT>>DATA\n (\n is a linebreak)

e.g.: workspace>>2

Events list

workspaceemitted on workspace change. Is emitted ONLY when a user requests a workspace change, and is not emitted on mouse movements (see activemon)WORKSPACENAME
workspacev2emitted on workspace change. Is emitted ONLY when a user requests a workspace change, and is not emitted on mouse movements (see activemon)WORKSPACEID,WORKSPACENAME
focusedmonemitted on the active monitor being changed.MONNAME,WORKSPACENAME
activewindowemitted on the active window being changed.WINDOWCLASS,WINDOWTITLE
activewindowv2emitted on the active window being changed.WINDOWADDRESS
fullscreenemitted when a fullscreen status of a window changes.0/1 (exit fullscreen / enter fullscreen)
monitorremovedemitted when a monitor is removed (disconnected)MONITORNAME
monitoraddedemitted when a monitor is added (connected)MONITORNAME
monitoraddedv2emitted when a monitor is added (connected)MONITORID,MONITORNAME,MONITORDESCRIPTION
createworkspaceemitted when a workspace is createdWORKSPACENAME
createworkspacev2emitted when a workspace is createdWORKSPACEID,WORKSPACENAME
destroyworkspaceemitted when a workspace is destroyedWORKSPACENAME
destroyworkspacev2emitted when a workspace is destroyedWORKSPACEID,WORKSPACENAME
moveworkspaceemitted when a workspace is moved to a different monitorWORKSPACENAME,MONNAME
moveworkspacev2emitted when a workspace is moved to a different monitorWORKSPACEID,WORKSPACENAME,MONNAME
renameworkspaceemitted when a workspace is renamedWORKSPACEID,NEWNAME
activespecialemitted when the special workspace opened in a monitor changes (closing results in an empty WORKSPACENAME)WORKSPACENAME,MONNAME
activelayoutemitted on a layout change of the active keyboardKEYBOARDNAME,LAYOUTNAME
closewindowemitted when a window is closedWINDOWADDRESS
movewindowemitted when a window is moved to a workspaceWINDOWADDRESS,WORKSPACENAME
movewindowv2emitted when a window is moved to a workspaceWINDOWADDRESS,WORKSPACEID,WORKSPACENAME
openlayeremitted when a layerSurface is mappedNAMESPACE
closelayeremitted when a layerSurface is unmappedNAMESPACE
submapemitted when a keybind submap changes. Empty means default.SUBMAPNAME
changefloatingmodeemitted when a window changes its floating mode. FLOATING is either 0 or 1.WINDOWADDRESS,FLOATING
urgentemitted when a window requests an urgent stateWINDOWADDRESS
minimizeemitted when a window requests a change to its minimized state. MINIMIZED is either 0 or 1.WINDOWADDRESS,MINIMIZED
screencastemitted when a screencopy state of a client changes. Keep in mind there might be multiple separate clients. State is 0/1, owner is 0 - monitor share, 1 - window shareSTATE,OWNER
windowtitleemitted when a window title changes.WINDOWADDRESS
ignoregrouplockemitted when ignoregrouplock is toggled.0/1
lockgroupsemitted when lockgroups is toggled.0/1
configreloadedemitted when the config is done reloadingempty
pinemitted when a window is pinned or unpinnedWINDOWADDRESS,PINSTATE
A fullscreen event is not guaranteed to fire on/off once in succession. Some windows may fire multiple requests to be fullscreened, resulting in multiple fullscreen events.

How to use socket2 with bash

Example script using socket2 events with bash and socat:


handle() {
  case $1 in
    monitoradded*) do_something ;;
    focusedmon*) do_something_else ;;

socat -U - UNIX-CONNECT:/tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock | while read -r line; do handle "$line"; done