hyprland-wiki/pages/Configuring/Advanced-config.md

This page documents all of the more advanced config options.

{{< hint type=important >}}

Please remember, that for ALL arguments separated by a comma, if you want to leave one of them empty, you cannot reduce the number of commas, unless told otherwise in a specific section:

three_param_keyword=A,B,C # OK

three_param_keyword=A,C # NOT OK

three_param_keyword=A,,C # OK

three_param_keyword=A,B, # OK

{{< /hint >}}

Table of contents

{{< toc format=html >}}

Workspaces

You have seven choices:

• ID: e.g. 1, 2, or 3

• Relative ID: e.g. +1, -3 or +100

• Relative workspace on monitor: e.g. m+1, m-1 or m+3

• Relative open workspace: e.g. e+1 or e-10

• Name: e.g. name:Web, name:Anime or name:Better anime

• Previous workspace: previous

• Special Workspace: special

{{< hint type=warning >}} special is supported ONLY on movetoworkspace. Any other dispatcher will result in undocumented behavior. {{< /hint >}}

Special Workspace

Special workspace is what is called a "scratchpad" in some other places. A workspace that you can toggle on/off on any monitor.

{{< hint >}} You cannot have floating windows in the Special workspace. Making a window floating will send it to the currently active real workspace. {{< /hint >}}

Workspace options

allfloat -> makes all new windows floating (also floats/unfloats windows on toggle)
allpseudo -> makes all new windows pseudo (also pseudos/unpseudos on toggle)

Executing

you can execute a shell script on startup of the compositor or on each time it's reloaded.

{{< hint type=info >}}

There currently is a bug with the exec that makes the executed app unable to die if killed, use SIGKILL (e.g. killall name -9) or launch from a script (exec-once=~/myscript.sh and do myapp & in the script)

{{< /hint >}}

exec-once=command will execute only on launch

exec=command will execute on each reload

Defining variables

You can define your own custom variables like this:

$VAR = value

for example:

$MyFavoriteGame = Among Us

then, to use them, simply use them. For example:

col.active_border=$MyColor

You ARE allowed to do this:

col.active_border=ff$MyRedValue1111

Sourcing (multi-file)

Use the source keyword to source another file.

For example, in your hyprland.conf you can:

source=~/.config/hypr/myColors.conf

And Hyprland will enter that file and parse it like a Hyprland config.

Please note it's LINEAR. Meaning lines above the source= will be parsed first, then lines inside ~/.config/hypr/myColors.conf, then lines below.

Gestures

Use something like libinput-gestures, with hyprctl if you want to expand Hyprland's gestures beyond what's offered in Basic Configuring.

Per-device input configs

Per-device config options will overwrite your options set in the input section. It's worth noting that ONLY values explicitly changed will be overwritten.

In order to apply per-device config options, make a new category like this:

device:name {

}

the name can be easily obtained by doing hyprctl devices.

Inside of it, put your config options. All options from the input category (and all subcategories, e.g. input:touchpad) can be put inside, EXCEPT:

force_no_accel, follow_mouse, float_switch_override_focus

For example:

device:ROYUAN Akko Multi-modes Keyboard-B {
    repeat_rate=50
    repeat_delay=500
    middle_button_emulation=0
}

remember about the space after the end of the device's name (before the {)!

{{< hint type=tip >}} With hyprctl, the category's spaces get turned into -, and everything is lowercase. So, for hyprctl calls, do for example:

hyprctl keyword device:royuan-akko-multi-modes-keyboard-b:kb_layout us

{{< /hint >}}

Wallpapers

The hyprland background you see when you first start Hyprland is NOT A WALLPAPER, it's the default image rendered at the bottom of the render stack.

To set a wallpaper, use a wallpaper utility like hyprpaper or swaybg.

Blurring layerSurfaces

LayerSurfaces are not windows. These are for example: Your wallpapers, notification overlays, bars, etc.

If you really want to blur them, use blurls=

blurls=NAMESPACE

where NAMESPACE is the namespace of the layerSurface. (You can get it from hyprctl layers)

to remove a namespace from being blurred (useful in dynamic situations) use:

blurls=remove,NAMESPACE