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

Variables

For basic syntax info, see Configuring Hyprland.

This page documents all the “options” of Hyprland. For binds, monitors, animations, etc. see the sidebar. For anything else, see Keywords.

Please keep in mind some options that are layout-specific will be documented in the layout pages and not here. (See the Sidebar for Dwindle and Master layouts)

Variable types

typedescription
intinteger
boolboolean, true or false (yes or no, 0 or 1) - any numerical value that is not 0 or 1 will cause undefined behaviour.
floatfloating point number
colorcolor (see hint below for color info)
vec2vector with 2 values (float), separated by a space (e.g. 0 0 or -10.9 99.1)
MODa string modmask (e.g. SUPER or SUPERSHIFT or SUPER + SHIFT or SUPER and SHIFT or CTRL_SHIFT or empty for none. You are allowed to put any separators you please except for a ,)
stra string
gradienta gradient, in the form of color color ... [angle] where color is a color (see above) and angle is an angle in degrees, in the format of 123deg e.g. 45deg (e.g. rgba(11ee11ff) rgba(1111eeff) 45deg) Angle is optional and will default to 0deg

Colors:

You have 3 options:

rgba(), e.g. rgba(b3ff1aee)

rgb(), e.g. rgb(b3ff1a)

legacy, e.g. 0xeeb3ff1a -> ARGB order

Mod list:

SHIFT CAPS CTRL/CONTROL ALT MOD2 MOD3 SUPER/WIN/LOGO/MOD4 MOD5

Sections

General

namedescriptiontypedefault
sensitivitymouse sensitivity (legacy, may cause bugs if not 1, prefer input:sensitivity)float1.0
border_sizeself-explanatoryint1
no_border_on_floatingdisable borders for floating windowsboolfalse
gaps_ingaps between windowsint5
gaps_outgaps between windows and monitor edgesint20
col.inactive_borderself-explanatorygradient0xffffffff
col.active_borderself-explanatorygradient0xff444444
cursor_inactive_timeoutin seconds, after how many seconds of cursor’s inactivity to hide it. Set to 0 for never.int0
layoutwhich layout to use. (Available: dwindle, master)strdwindle
no_cursor_warpsif true, will not warp the cursor in many cases (focusing, keybinds, etc)boolfalse
apply_sens_to_rawif on, will also apply the sensitivity to raw mouse output (e.g. sensitivity in games) NOTICE: really not recommended.boolfalse
Prefer using input:sensitivity over general:sensitivity to avoid bugs, especially with Wine/Proton apps.

Decoration

namedescriptiontypedefault
roundingrounded corners’ radius (in layout px)int0
multisample_edgesenable antialiasing (no-jaggies) for rounded cornersbooltrue
active_opacityself-explanatory, only for windows. (0.0 - 1.0)float1.0
inactive_opacityself-explanatory, only for windows. (0.0 - 1.0)float1.0
fullscreen_opacityself-explanatory, only for windows. (0.0 - 1.0)float1.0
blurenable kawase window background blurbooltrue
blur_sizeblur size (distance)int8
blur_passesthe amount of passes to performint1
blur_ignore_opacitymake the blur layer ignore the opacity of the windowboolfalse
blur_new_optimizationswhether to enable further optimizations to the blur. Recommended to leave on, as it will massively improve performance.booltrue
blur_xrayif enabled, floating windows will ignore tiled windows in their blur. Only available if blur_new_optimizations is true. Will reduce overhead on floating blur significantly.boolfalse
drop_shadowenable drop shadows on windowsbooltrue
shadow_rangeShadow range (“size”) in layout pxint4
shadow_render_power(1 - 4), in what power to render the falloff (more power, the faster the falloff)int3
shadow_ignore_windowif true, the shadow will not be rendered behind the window itself, only around it.booltrue
col.shadowshadow’s color. Alpha dictates shadow’s opacity.color0xee1a1a1a
col.shadow_inactiveinactive shadow color. (if not set, will fall back to col.shadow)colorunset
shadow_offsetshadow’s rendering offset.vec2[0, 0]
shadow_scaleshadow’s scale. 0.0 - 1.0float1.0
dim_inactiveenables dimming of inactive windowsboolfalse
dim_strengthhow much inactive windows should be dimmed, 0.0 - 1.0float0.5
dim_specialhow much to dim the rest of the screen by when a special workspace is open. 0.0 - 1.0float0.2
dim_aroundhow much the dimaround window rule should dim by. 0.0 - 1.0float0.4
screen_shadera path to a custom shader to be applied at the end of rendering. See examples/screenShader.frag for an example.str[EMPTY]

blur_size and blur_passes have to be at least 1.

Increasing blur_passes is necessary to prevent blur looking wrong on higher blur_size values, but remember that higher blur_passes will require more strain on the GPU.

It will, however, cause zero overhead on tiled windows if using blur_new_optimizations.

Animations

namedescriptiontypedefault
enabledenable animationsbooltrue

Input

Input

namedescriptiontypedefault
kb_modelAppropriate XKB keymap parameter. See the note below.str[EMPTY]
kb_layoutAppropriate XKB keymap parameterstrus
kb_variantAppropriate XKB keymap parameterstr[EMPTY]
kb_optionsAppropriate XKB keymap parameterstr[EMPTY]
kb_rulesAppropriate XKB keymap parameterstr[EMPTY]
kb_fileIf you prefer, you can use a path to your custom .xkb file.str[EMPTY]
numlock_by_defaultEngage numlock by default.boolfalse
repeat_rateThe repeat rate for held-down keys, in repeats per second.int25
repeat_delayDelay before a held-down key is repeated, in milliseconds.int600
sensitivitySets the mouse input sensitivity. Value will be clamped to the range -1.0 to 1.0. libinput#pointer-accelerationfloat0.0
accel_profileSets the cursor acceleration profile. Can be one of adaptive, flat. Leave empty to use libinput’s default mode for your input device. libinput#pointer-accelerationstr[EMPTY]
force_no_accelForce no cursor acceleration. This bypasses most of your pointer settings to get as raw of a signal as possible. Enabling this is not recommended due to potential cursor desynchronization.boolfalse
left_handedSwitches RMB and LMBboolfalse
scroll_methodSets the scroll method. Can be one of 2fg (2 fingers), edge, on_button_down, no_scroll. libinput#scrollingstr[EMPTY]
scroll_buttonSets the scroll button. Has to be an int, cannot be a string. Check wev if you have any doubts regarding the ID. 0 means default.int0
natural_scrollInverts scrolling direction. When enabled, scrolling moves content directly instead of manipulating a scrollbar.boolfalse
follow_mouse(0/1/2/3) Specify if and how cursor movement should affect window focus. See the note below.int1
float_switch_override_focusIf enabled (1 or 2), focus will change to the window under the cursor when changing from tiled-to-floating and vice versa. If 2, focus will also follow mouse on float-to-float switches.int1

XKB Settings

You can find a list of models, layouts, variants and options in /usr/share/X11/xkb/rules/base.lst. Alternatively, you can use the localectl command to discover what is available on your system.

For switchable keyboard configurations, take a look at the uncommon tips & tricks page entry.

Follow Mouse Cursor

  • 0 - Cursor movement will not change focus.
  • 1 - Cursor movement will always change focus to the window under the cursor.
  • 2 - Cursor focus will be detached from keyboard focus. Clicking on a window will move keyboard focus to that window.
  • 3 - Cursor focus will be completely separate from keyboard focus. Clicking on a window will not change keyboard focus.

Touchpad

Subcategory input:touchpad:

namedescriptiontypedefault
disable_while_typingDisable the touchpad while typing.booltrue
natural_scrollInverts scrolling direction. When enabled, scrolling moves content directly instead of manipulating a scrollbar.boolfalse
scroll_factorMultiplier applied to the amount of scroll movement.float1.0
middle_button_emulationSending LMB and RMB simultaneously will be interpreted as a middle click. This disables any touchpad area that would normally send a middle click based on location. libinput#middle-button-emulationboolfalse
clickfinger_behaviorButton presses with 1, 2, or 3 fingers will be mapped to LMB, RMB, and MMB respectively. This disables interpretation of clicks based on location on the touchpad. libinput#clickfinger-behaviorboolfalse
tap-to-clickTapping on the touchpad with 1, 2, or 3 fingers will send LMB, RMB, and MMB respectively.booltrue
drag_lockWhen enabled, lifting the finger off for a short time while dragging will not drop the dragged item. libinput#tap-and-dragboolfalse

A subcategory is a nested category:

input {
    # ...
    # ...

    touchpad {
        # ...
        # ...
    }
}

Doing input:touchpad { is invalid!

Touchdevice

Subcategory input:touchdevice:

namedescriptiontypedefault
transformtransform the input from touchdevices. The possible transformations are the same as those of the monitorsint0
outputthe output to bind touch devices. Empty means unset and will use the current / autodetected.string[EMPTY]

Per-device input config

Described here.

Gestures

namedescriptiontypedefault
workspace_swipeenable workspace swipe gestureboolfalse
workspace_swipe_fingershow many fingers for the gestureint3
workspace_swipe_distancein px, the distance of the gestureint300
workspace_swipe_invertinvert the directionbooltrue
workspace_swipe_min_speed_to_forceminimum speed in px per timepoint to force the change ignoring cancel_ratio. Setting to 0 will disable this mechanic.int30
workspace_swipe_cancel_ratio(0.0 - 1.0) how much the swipe has to proceed in order to commence it. (0.7 -> if > 0.7 * distance, switch, if less, revert)float0.5
workspace_swipe_create_newwhether a swipe right on the last workspace should create a new one.booltrue
workspace_swipe_foreverif enabled, swiping will not clamp at the neighboring workspaces but continue to the further ones.boolfalse
workspace_swipe_numberedif enabled, swiping will swipe on consecutive numbered workspaces.boolfalse

Misc

namedescriptiontypedefault
disable_hyprland_logodisables the hyprland logo background. :(boolfalse
disable_splash_renderingdisables the hyprland splash rendering. (requires a monitor reload to take effect)boolfalse
no_vfrdisables VFR (variable frame rate) - VFR increases battery life at the expense of possible issues on a few monitors.booltrue
mouse_move_enables_dpmsIf DPMS is set to off, wake up the monitors if the mouse moves.boolfalse
always_follow_on_dndWill make mouse focus follow the mouse when drag and dropping. Recommended to leave it enabled, especially for people using focus follows mouse at 0.booltrue
layers_hog_keyboard_focusIf true, will make keyboard-interactive layers keep their focus on mouse move (e.g. wofi, bemenu)booltrue
animate_manual_resizesIf true, will animate manual window resizes/movesboolfalse
disable_autoreloadIf true, the config will not reload automatically on save, and instead needs to be reloaded with hyprctl reload. Might save on battery.boolfalse
enable_swallowEnable window swallowingboolfalse
swallow_regexThe class regex to be used for windows that should be swallowed (usually, a terminal)str[EMPTY]
focus_on_activateWhether Hyprland should focus an app that requests to be focused (an activate request)boolfalse
no_direct_scanoutDisables direct scanout. Direct scanout attempts to reduce lag when there is only one fullscreen application on a screen (e.g. game)boolfalse
hide_cursor_on_touchHides the cursor when the last input was a touch input until a mouse input is done.booltrue

Binds

namedescriptiontypedefault
pass_mouse_when_boundif disabled, will not pass the mouse events to apps / dragging windows around if a keybind has been triggered.boolfalse
scroll_event_delayin ms, how many ms to wait after a scroll event to allow to pass another one for the binds.int300
workspace_back_and_forthIf enabled, an attempt to switch to the currently focused workspace will instead switch to the previous workspace. Akin to i3’s auto_back_and_forth.boolfalse
allow_workspace_cyclesIf enabled, workspaces don’t forget their previous workspace, so cycles can be created by switching to the first workspace in a sequence, then endlessly going to the previous workspace.boolfalse
focus_preferred_methodsets the preferred focus finding method when using focuswindow/movewindow/etc with a direction. 0 - history (recent have priority), 1 - length (longer shared edges have priority)int0

Debug

Only for developers.
namedescriptiontypedefault
overlayprint the debug performance overlay. Disable VFR for accurate results.boolfalse
damage_blink(epilepsy warning!) flash areas updated with damage trackingboolfalse
disable_logsself-explanatoryboolfalse
disable_timedisables time loggingbooltrue
damage_trackingredraw only the needed bits of the display. Do not change. (default: full - 2) monitor - 1, none - 0int2

More

There are more config options described in other pages, which are layout- or circumstance-specific. See the sidebar for more pages.