IPC

IPC

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

Hyprland Instance Signature (HIS)

echo $HYPRLAND_INSTANCE_SIGNATURE

$XDG_RUNTIME_DIR/hypr/[HIS]/.socket.sock

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

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

$XDG_RUNTIME_DIR/hypr/[HIS]/.socket2.sock

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

name description data
workspace emitted on workspace change. Is emitted ONLY when a user requests a workspace change, and is not emitted on mouse movements (see activemon) WORKSPACENAME
workspacev2 emitted on workspace change. Is emitted ONLY when a user requests a workspace change, and is not emitted on mouse movements (see activemon) WORKSPACEID,WORKSPACENAME
focusedmon emitted on the active monitor being changed. MONNAME,WORKSPACENAME
activewindow emitted on the active window being changed. WINDOWCLASS,WINDOWTITLE
activewindowv2 emitted on the active window being changed. WINDOWADDRESS
fullscreen emitted when a fullscreen status of a window changes. 0/1 (exit fullscreen / enter fullscreen)
monitorremoved emitted when a monitor is removed (disconnected) MONITORNAME
monitoradded emitted when a monitor is added (connected) MONITORNAME
monitoraddedv2 emitted when a monitor is added (connected) MONITORID,MONITORNAME,MONITORDESCRIPTION
createworkspace emitted when a workspace is created WORKSPACENAME
createworkspacev2 emitted when a workspace is created WORKSPACEID,WORKSPACENAME
destroyworkspace emitted when a workspace is destroyed WORKSPACENAME
destroyworkspacev2 emitted when a workspace is destroyed WORKSPACEID,WORKSPACENAME
moveworkspace emitted when a workspace is moved to a different monitor WORKSPACENAME,MONNAME
moveworkspacev2 emitted when a workspace is moved to a different monitor WORKSPACEID,WORKSPACENAME,MONNAME
renameworkspace emitted when a workspace is renamed WORKSPACEID,NEWNAME
activespecial emitted when the special workspace opened in a monitor changes (closing results in an empty WORKSPACENAME) WORKSPACENAME,MONNAME
activelayout emitted on a layout change of the active keyboard KEYBOARDNAME,LAYOUTNAME
openwindow emitted when a window is opened WINDOWADDRESS,WORKSPACENAME,WINDOWCLASS,WINDOWTITLE
closewindow emitted when a window is closed WINDOWADDRESS
movewindow emitted when a window is moved to a workspace WINDOWADDRESS,WORKSPACENAME
movewindowv2 emitted when a window is moved to a workspace WINDOWADDRESS,WORKSPACEID,WORKSPACENAME
openlayer emitted when a layerSurface is mapped NAMESPACE
closelayer emitted when a layerSurface is unmapped NAMESPACE
submap emitted when a keybind submap changes. Empty means default. SUBMAPNAME
changefloatingmode emitted when a window changes its floating mode. FLOATING is either 0 or 1. WINDOWADDRESS,FLOATING
urgent emitted when a window requests an urgent state WINDOWADDRESS
minimize emitted when a window requests a change to its minimized state. MINIMIZED is either 0 or 1. WINDOWADDRESS,MINIMIZED
screencast emitted 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 share STATE,OWNER
windowtitle emitted when a window title changes. WINDOWADDRESS
togglegroup emitted when togglegroup command is used.
returns state,handle where the state is a toggle status and the handle is one or more window addresses separated by a comma
e.g. 0,0x64cea2525760,0x64cea2522380 where 0 means that a group has been destroyed and the rest informs which windows were part of it
0/1,WINDOWADDRESS(ES)
moveintogroup emitted when the window is merged into a group. returns the address of a merged window WINDOWADDRESS
moveoutofgroup emitted when the window is removed from a group. returns the address of a removed window WINDOWADDRESS
ignoregrouplock emitted when ignoregrouplock is toggled. 0/1
lockgroups emitted when lockgroups is toggled. 0/1
configreloaded emitted when the config is done reloading empty
pin emitted when a window is pinned or unpinned WINDOWADDRESS,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:

#!/bin/sh

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

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