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 focusedmon) | WORKSPACENAME |
| workspacev2 | emitted on workspace change. Is emitted ONLY when a user requests a workspace change, and is not emitted on mouse movements (see focusedmon) | WORKSPACEID,WORKSPACENAME |
| focusedmon | emitted on the active monitor being changed. | MONNAME,WORKSPACENAME |
| focusedmonv2 | emitted on the active monitor being changed. | MONNAME,WORKSPACEID |
| 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 |
| 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 |
| windowtitlev2 | emitted when a window title changes. | WINDOWADDRESS,WINDOWTITLE |
| 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 commae.g. 0,64cea2525760,64cea2522380 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