# Complete List of Hyprland IPC Socket Events: Reference and Usage Guide

> Explore Hyprland IPC socket events. Discover over 30 event types like workspace, window, monitor, and input events for detailed compositor state changes. Master Hyprland customization.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: api-reference
- Published: 2026-07-26

---

**Hyprland exposes compositor state changes through a Unix-domain socket at `.socket2.sock`, emitting over 30 distinct event types—including workspace, window, monitor, and input events—in a `event>>payload` format.**

The Hyprland Wayland compositor (hyprwm/Hyprland) provides an IPC socket that allows external programs to react to compositor state changes in real-time. Every event follows a standardized format defined in the `CEventManager` class, making it possible to build status bars, notification daemons, and automation scripts that respond instantly to window management actions.

## How the Hyprland IPC Socket Works

Hyprland's IPC mechanism centers around the `CEventManager` singleton (`g_pEventManager`), defined in [`src/managers/EventManager.hpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/EventManager.hpp). When the compositor triggers a state change, it constructs a `SHyprIPCEvent` struct containing the event name and data payload:

```cpp
struct SHyprIPCEvent {
    std::string event;   // e.g. "workspace"
    std::string data;    // payload, format defined per-event
};

```

The manager formats each event as `<event>>[payload]\n` in `CEventManager::formatEvent` ([`src/managers/EventManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/EventManager.cpp), lines 26-31). Payloads are truncated to 1 KB, with internal newlines replaced by spaces to ensure single-line messages. The socket itself is created at `g_pCompositor->m_instancePath + "/.socket2.sock"` (see the constructor in [`src/managers/EventManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/EventManager.cpp), lines 14-30).

Clients connecting to this non-blocking Unix socket receive a stream of newline-terminated messages. The manager maintains a queue of up to **64 events per client** (`MAX_QUEUED_EVENTS` in [`src/managers/EventManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/EventManager.cpp), lines 69-78); exceeding this limit causes the client to be dropped.

## Complete List of Available IPC Events

The compositor emits events from multiple subsystems. Each event name is broadcast exactly as shown, followed by the specified payload format.

### Workspace Events

Emitted by [`src/state/WorkspacePlacementController.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/state/WorkspacePlacementController.cpp) and [`src/desktop/Workspace.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/Workspace.cpp):

- **`workspace`** / **`workspacev2`** — Workspace changed. Payload: `name` (v1) or `id,name` (v2). Source: lines 224-226.
- **`moveworkspace`** / **`moveworkspacev2`** — Workspace moved to another monitor. Payload: `srcWS,dstMonitor` (v1) or `srcID,srcWS,dstMonitor` (v2). Source: lines 230-233.
- **`createworkspace`** / **`createworkspacev2`** — New workspace created. Payload: `name` (v1) or `id,name` (v2). Source: [`src/desktop/Workspace.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/Workspace.cpp), lines 72-73.
- **`destroyworkspace`** / **`destroyworkspacev2`** — Workspace destroyed. Payload: `name` (v1) or `id,name` (v2). Source: lines 81-82.
- **`renameworkspace`** — Workspace renamed. Payload: `id,newName`. Source: line 543.
- **`changeworkspaceid`** — Workspace ID modified. Payload: `oldID,newID`. Source: line 560.

### Monitor Events

Emitted by [`src/output/Monitor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/output/Monitor.cpp) and [`src/desktop/state/FocusState.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/state/FocusState.cpp):

- **`monitoradded`** / **`monitoraddedv2`** — New output connected. Payload: `name` (v1) or `id,name,shortDesc` (v2). Source: [`Monitor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/Monitor.cpp), lines 387-388.
- **`monitorremoved`** / **`monitorremovedv2`** — Output disconnected. Payload: `name` (v1) or `id,name,shortDesc` (v2). Source: lines 397-398.
- **`focusedmon`** / **`focusedmonv2`** — Focus changed to different monitor. Payload: `monitor,workspaceName` (v1) or `monitor,workspaceID` (v2). Source: [`FocusState.cpp`](https://github.com/hyprwm/Hyprland/blob/main/FocusState.cpp), lines 287-288.

### Window and Layer Events

Emitted by [`src/desktop/view/Window.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/view/Window.cpp), [`src/desktop/view/LayerSurface.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/view/LayerSurface.cpp), and related files:

- **`openwindow`** — Window created. Payload: `XID,workspace,class,title`. Source: [`Window.cpp`](https://github.com/hyprwm/Hyprland/blob/main/Window.cpp), lines 2369-2370.
- **`closewindow`** — Window closed. Payload: `XID`. Source: line 2574.
- **`movewindow`** / **`movewindowv2`** — Window moved to different workspace. Payload: `XID,workspaceName` (v1) or `XID,workspaceID,workspaceName` (v2). Source: lines 579-580.
- **`windowtitle`** / **`windowtitlev2`** — Window title changed. Payload: `XID` (v1) or `XID,title` (v2). Source: lines 1452-1453.
- **`activewindow`** / **`activewindowv2`** — Focus changed to different window. Payload: `class,title` (v1) or `XID` (v2). Source: [`FocusState.cpp`](https://github.com/hyprwm/Hyprland/blob/main/FocusState.cpp), lines 209-210.
- **`urgent`** — Window demands attention. Payload: `XID`. Source: [`Window.cpp`](https://github.com/hyprwm/Hyprland/blob/main/Window.cpp), line 1371.
- **`fullscreen`** — Fullscreen state toggled. Payload: `0` (false) or `1` (true). Source: [`src/managers/fullscreen/FullscreenController.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/fullscreen/FullscreenController.cpp), line 482.
- **`changefloatingmode`** — Floating mode toggled. Payload: `XID,0|1`. Source: [`src/layout/LayoutManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/layout/LayoutManager.cpp), lines 47-50.
- **`togglegroup`** — Window entered or left a group. Payload: `1|0,XID` (enter/leave). Source: [`src/desktop/view/Group.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/view/Group.cpp), lines 66-82.
- **`openlayer`** / **`closelayer`** — Layer surface (like waybar or notifications) opened or closed. Payload: `layerNamespace`. Source: [`src/desktop/view/LayerSurface.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/view/LayerSurface.cpp), lines 218-227.
- **`minimized`** — Wayland toplevel minimized state changed. Payload: `XID,1|0` (minimized/restored). Source: [`src/protocols/ForeignToplevelWlr.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/protocols/ForeignToplevelWlr.cpp), lines 126-138.

### Input and Layout Events

Emitted by [`src/managers/input/InputManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/input/InputManager.cpp) and [`src/config/shared/actions/ConfigActions.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/shared/actions/ConfigActions.cpp):

- **`kill`** — Window kill signal sent. Payload: `XID`. Source: [`InputManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/InputManager.cpp), line 947.
- **`activelayout`** — Keyboard layout changed. Payload: `keyboard,layoutName`. Source: lines 1183-1184.
- **`pin`** — Window pinned state toggled. Payload: `XID,0|1`. Source: [`ConfigActions.cpp`](https://github.com/hyprwm/Hyprland/blob/main/ConfigActions.cpp), line 265.
- **`submap`** — Keymap submap changed. Payload: empty string, or name of the new submap. Source: lines 1664-1672.
- **`lockgroups`** — Group locking toggled. Payload: `1` or `0`. Source: line 1277.

### System and Configuration Events

- **`configreloaded`** — Configuration file reloaded. Payload: *(empty)*. Source: [`src/config/lua/ConfigManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/config/lua/ConfigManager.cpp), line 848.
- **`bell`** — XDG notification bell triggered. Payload: *(none)*. Source: [`src/protocols/XDGBell.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/protocols/XDGBell.cpp), lines 17-47.
- **`screencast`** / **`screencastv2`** — Screensharing started or stopped. Payload: `1|0,type` (v1) or `1|0,type,name` (v2). Source: [`src/managers/screenshare/ScreenshareSession.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/screenshare/ScreenshareSession.cpp), lines 140-148.
- **`custom`** — User-defined event emitted via configuration. Payload: arbitrary string supplied by the user. Source: [`ConfigActions.cpp`](https://github.com/hyprwm/Hyprland/blob/main/ConfigActions.cpp), line 1266.

## Listening to IPC Events

You can monitor these events using standard Unix socket tools or the built-in `hyprctl` utility.

### Using netcat (nc)

Connect directly to the socket path, which resides under `$XDG_RUNTIME_DIR/hypr/`:

```bash

# Print raw events as they arrive

socket="${XDG_RUNTIME_DIR}/hypr/.socket2.sock"
nc -U "$socket"

```

### Parsing Events in Shell Scripts

Parse the `event>>payload` format in Bash to trigger specific actions:

```bash
#!/usr/bin/env bash
socket="${XDG_RUNTIME_DIR}/hypr/.socket2.sock"

while IFS= read -r line; do
    # Split on ">>"

    IFS='>>' read -r ev payload <<< "$line"
    case "$ev" in
        workspace)    notify-send "Workspace" "Changed to: $payload" ;;
        activewindow) echo "Active class: ${payload%%,*}" ;;
        monitoradded) echo "New monitor: $payload" ;;
        urgent)       notify-send "Urgent window" "$payload" ;;
    esac
done < <(nc -U "$socket")

```

### Using hyprctl

Hyprland ships with `hyprctl`, which includes a built-in events command:

```bash

# Stream all events with automatic socket detection

hyprctl events

```

To query specific state information rather than streaming events, use the request socket (`.socket.sock`), though this returns static data rather than event streams:

```bash

# Get current active window class

echo "activewindow>>" | nc -U "${XDG_RUNTIME_DIR}/hypr/.socket.sock" | cut -d',' -f1

```

## Summary

- **Hyprland IPC events** flow through a Unix socket at `.socket2.sock` managed by `CEventManager` in [`src/managers/EventManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/EventManager.cpp).
- Over **30 event types** cover workspaces, monitors, windows, layers, input devices, and configuration changes.
- Events follow the format **`event>>payload\n`**, with payloads truncated to 1 KB and newlines sanitized.
- The event queue limits clients to **64 buffered messages**; overflow disconnects the client.
- Usage requires parsing the stream with tools like `nc`, `socat`, or the built-in `hyprctl events` command.

## Frequently Asked Questions

### What is the difference between v1 and v2 event versions?

**V2 events include numerical IDs alongside string names.** For example, `workspace` sends only the workspace name, while `workspacev2` sends `id,name`. Similarly, `activewindowv2` sends the window's XID (numerical identifier) instead of the class and title strings. Use v2 events when your script needs stable identifiers that persist across renaming operations.

### Where is the IPC socket located?

**The socket path is constructed at runtime as `$XDG_RUNTIME_DIR/hypr/.socket2.sock`.** The exact directory includes the compositor instance name, but under standard configurations, this resolves to `/run/user/1000/hypr/.socket2.sock` (where `1000` is your UID). The `hyprctl` utility automatically detects this path, or you can locate it via the `$HYPRLAND_INSTANCE_SIGNATURE` environment variable.

### Can I emit custom events through the IPC socket?

**Yes, using the `custom` event type.** You can trigger custom events from Hyprland configuration files or keybindings using the `ipc` dispatcher, which accepts an arbitrary string payload. These events broadcast to all connected IPC clients with the event name `custom` and your supplied data, enabling integration between Hyprland bindings and external scripts.

### What happens if my script cannot keep up with event production?

**The Event Manager drops clients that exceed the 64-event buffer.** If your script blocks or processes events too slowly, once the queue fills, Hyprland disconnects that client to prevent memory bloat. For reliable operation, ensure your event loop reads continuously or runs in a separate thread, and consider using `hyprctl events` which handles buffering internally.