Hyprland Wiki
Contribute to the Wiki!Toggle Dark/Light/Auto modeToggle Dark/Light/Auto modeToggle Dark/Light/Auto modeBack to homepage


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 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
focusedmonemitted on the active monitor being changed.MONNAME,WORKSPACENAME
activewindowemitted on the active window being changed.WINDOWCLASS,WINDOWTITLE
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
createworkspaceemitted when a workspace is createdWORKSPACENAME
destroyworkspaceemitted when a workspace is destroyedWORKSPACENAME
moveworkspaceemitted when a workspace is moved to a different monitorWORKSPACENAME,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
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
A fullscreen event is not guaranteed to fire on/off once in succession. A window might do for example 3 requests to be fullscreen’d, which would result in 3 fullscreen events.

How to use socket2 with bash

example script using socket2 events with bash and socat:


function handle {
  if [[ ${1:0:12} == "monitoradded" ]]; then
    # do_something

socat - UNIX-CONNECT:/tmp/hypr/$(echo $HYPRLAND_INSTANCE_SIGNATURE)/.socket2.sock | while read line; do handle $line; done