hyprctl

hyprctl [command] [arguments]

hyprctl is the command-line control utility for Hyprland, a dynamic tiling Wayland compositor. It talks to the running compositor over its IPC socket to query state (monitors, workspaces, clients, devices) and to trigger actions at runtime, and is installed automatically alongside Hyprland.Dispatchers control actions like moving windows, changing workspaces, and executing programs, invoked via `hyprctl dispatch <DISPATCHER> [ARGS]`. Common dispatchers include exec, killactive, workspace, movewindow, fullscreen, and togglefloating; see the Dispatchers page in the Hyprland wiki for the full list.Runtime config values are read with getoption and set with keyword SECTION.OPTION VALUE; changes made this way are lost on the next reload unless also written to the config file. Since Hyprland added optional Lua-based configuration (`hyprland.lua`), hyprctl eval and hyprctl repl expose the same Lua API (`hl.dispatch`, `hl.config`, etc.) for scripting, alongside the traditional keyword/dispatch interface which still works for `hyprland.conf`-based setups.Because hyprctl calls are handled synchronously by the compositor, issuing many of them in quick succession (e.g. from a script) can cause visible stutter - use --batch to bundle several commands into a single request instead.

reload

Reload Hyprland configuration

Show active window information

List input devices

List workspaces

List monitors and properties

List all windows/clients

Execute a dispatcher (window actions, workspace changes)

Set configuration option at runtime

Set cursor theme and size

Switch keyboard layout (CMD is `next`, `prev`, or a layout index)

Print the current value of a config option, e.g. `getoption general.border_size`

List layer-shell surfaces (bars, launchers, notifications, etc.)

Show an on-screen notification using Hyprland's built-in notification system

Set (or clear) a persistent error bar message

Run a Lua expression against the Lua config API (e.g. `hl.dispatch(...)`), added alongside Hyprland's optional Lua config

Start an interactive Lua REPL for the same API used by eval

Add or remove a fake output (`wayland`, `headless`, or `auto` backend)

Execute multiple commands in one request, separated by semicolons - cuts down IPC round-trips versus many separate calls

Output in JSON format

Force a state refresh after issuing the command (e.g. after a layout or rule change)

Target a specific Hyprland instance (id or index from `hyprctl instances`) when more than one is running

Only works when Hyprland is running, and talks only to the local Hyprland instance(s) via a Unix socket under `$XDGRUNTIMEDIR/hypr`. Changes made via keyword don't persist across restarts or reloads unless also saved to the config file. The Lua config system (and thus eval/repl) is optional and only active if `~/.config/hypr/hyprland.lua` exists; otherwise Hyprland falls back to the classic `hyprland.conf`.

hyprctl is part of the Hyprland project, a Wayland compositor created by Vaxry, first released in 2022 and known for its animations, dynamic tiling, and extensive customization. In 2026, Hyprland 0.55 added an optional Lua configuration system, extending hyprctl with the eval and repl commands for scripting alongside its existing keyword/dispatch interface.

hyprpaper(1), hyprshot(1), swaymsg(1)

Source code · Homepage · Documentation