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

Using Hyprctl

hyprctl is a utility for controlling some parts of the compositor from a CLI or a script. If you install with make install, or any package, it should automatically be installed.

To check if hyprctl is installed, simply execute it by issuing hyprctl in the terminal.

If it’s not, go to the repo root and /hyprctl. Issue a make all and then sudo cp ./hyprctl /usr/bin.

Using Hyprctl

hyprctl calls will be dispatched by the compositor synchronously, meaning any spam of the utility will cause slowdowns. It’s recommended to use --batch for many control calls, and limiting the amount of info calls.

For live event handling, see the socket2.



issue a dispatch to call a keybind dispatcher with an arg.

An arg has to be present, for dispatchers without parameters it can be anything.

To pass an argument starting with - or --, such as command line options to exec programs, pass -- as an option. This will disable any subsequent parsing of options by hyprctl.


hyprctl dispatch exec kitty

hyprctl dispatch -- exec kitty --single-instance

hyprctl dispatch pseudo x

Returns: ok on success, an error message on fail.

See Dispatchers for a list of dispatchers.


issue a keyword to call a config keyword dynamically.


hyprctl keyword bind SUPER,O,pseudo

hyprctl keyword general:border_size 10

hyprctl keyword monitor DP-3,[email protected],0x0,1

Returns: ok on success, an error message on fail.


issue a reload to force reload the config.


issue a kill to get into a kill mode, where you can kill an app by clicking on it. You can exit it with ESCAPE.

Kind of like xkill.


Sets the cursor theme and reloads the cursor manager. Will set the theme for everything except GTK, because GTK.

params: theme and size


hyprctl setcursor Bibata-Modern-Classic 24


Allows you to add and remove fake outputs to your preferred backend.

params: create or remove and backend or name respectively.

For create:

pass a backend name: wayland, x11, headless or auto. On a real hyprland session, if you’re looking for a VNC / RDP type thing, it’s 99% going to be headless.

For remove:

pass the output’s name, as found in hyprctl monitors. Please be aware you are not allowed to remove real displays with this command.


# will create a 1920x1080 headless display, for example to use with RDP.
hyprctl output create headless

# will remove the above display, provided its name was HEADLESS-1
hyprctl output remove HEADLESS-1


Sets the xkb layout index for a keyboard.

For example, if you set:

device:my-epic-keyboard-v1 {

You can use this command to switch between them.

hyprctl switchxkblayout [DEVICE] [CMD]

where CMD is either next for next, prev for previous, or ID for a specific one (in the above case, us: 0, pl: 1, de: 2)


Sets the hyprctl error string. Will reset when Hyprland’s config is reloaded.

hyprctl seterror rgba(66ee66ff) hello world this is my problem

or disable:

hyprctl seterror disable


Sets a window prop. Can be locked by adding lock at the end. If lock is not added, will be unlocked. Locking means a dynamic windowrule cannot override this setting.

Prop List:

animationstylestring, cannot be locked
roundingint, -1 means not overriden
forceallowsinput0/1, forceinput rule
alphaoverride0/1, makes the next setting be override instead of multiply
alphafloat 0.0 - 1.0
alphainactiveoverride0/1, makes the next setting be override instead of multiply
alphainactivefloat 0.0 - 1.0
activebordercolorcolor, -1 means not set
inactivebordercolorcolor, -1 means not set
hyprctl setprop address:0x13371337 forcenoanims 1 lock  # with locking
hyprctl setprop address:0x13371337 nomaxsize 0          # without locking


version - prints the hyprland version, meaning flags, commit and branch of build.
monitors - lists all the outputs with their properties
workspaces - lists all workspaces with their properties
clients - lists all windows with their properties
devices - lists all connected keyboards and mice
binds - lists all registered binds
activewindow - gets the active window name
layers - lists all the layers
splash - prints the current random splash
getoption [option] - gets the config option status (values)
cursorpos - gets the current cursor pos in global layout coordinates
animations - gets the current config'd info about animations and beziers

For the getoption command, the option name should be written as section:option, e.g.:

hyprctl getoption general:border_size

# For nested sections:
hyprctl getoption input:touchpad:disable_while_typing

See Variables for section and options you can use.


You can also use --batch to specify a batch of commands to execute


hyprctl --batch "keyword general:border_size 2 ; keyword general:gaps_out 20"

; separates the commands


You can specify flags for the request like this:

hyprctl -j monitors

flag list:

j -> output in JSON