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

Basic Config

For basic syntax info, see Master Configuring.

This page documents all the “options” of Hyprland. For binds, monitors, execs, curves, etc. see Advanced Configuring.

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

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 (e.g. 0x22334455 - alpha 0x22, red 0x33, green 0x44, blue 0x55)
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 orSUPERSHIFTALTCTRLCAPSMOD2MOD3MOD5 or empty for none)

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
apply_sens_to_rawif on, will also apply the sensitivity to raw mouse output (e.g. sensitivity in games)boolfalse
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-explanatorycolor0xffffffff
col.active_borderself-explanatorycolor0xff444444
cursor_inactive_timeoutin seconds, after how many seconds of cursor’s inactivity to hide it. Set to 0 for never.int0
damage_trackingMakes the compositor redraw only the needed bits of the display. Saves on resources by not redrawing when not needed. Available modes: none, monitor, full. You don’t need to know what different modes do, just always use full.strfull
layoutwhich layout to use. (Available: dwindle, master)strdwindle
no_cursor_warpsif true, will not warp the cursor in many cases (focusing, keybinds, etc)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 turn on, as it will massively improve performance, but some people have experienced graphical issuesboolfalse
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]
dim_inactiveenables dimming of inactive windowsboolfalse
dim_strengthhow much inactive windows should be dimmed, 0.0 - 1.0float0.5

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.

Using blur_new_optimizations with an animated wallpaper may actually increase GPU usage.

Animations

namedescriptiontypedefault
enabledenable animationsbooltrue
More about animations is on the Advanced Configuring page.

Input

namedescriptiontypedefault
kb_layoutAppropriate XKB keymap parameterstrus
kb_variantAppropriate XKB keymap parameterstr[EMPTY]
kb_modelAppropriate 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 an .xkb file.str[EMPTY]
follow_mouse(0/1/2/3) enable mouse following (focus on enter new window) - See the note below for more infoint1
float_switch_override_focusif enabled, focus will follow mouse if changing from tiled to floating and vice versabooltrue
repeat_ratein ms, the repeat rate for held keysint25
repeat_delayin ms, the repeat delay (grace period) before the spamint600
natural_scrollenable natural scrollboolfalse
numlock_by_defaultlock numlock by defaultboolfalse
force_no_accelforce no mouse acceleration, bypasses most of your pointer settings to get as raw of a signal as possible.boolfalse
sensitivityset the libinput sensitivity. This HAS to be from -1 to 1, or else it will be clamped.float0.0

Follow Mouse

  • 0 - disabled
  • 1 - full
  • 2 - loose. Will focus mouse on other windows on focus but not the keyboard.
  • 3 - full loose, will not refocus on click, but allow mouse focus to be detached from the keyboard like in 2.
For switchable keyboard configs, take a look at the uncommon tips & tricks page entry.

Touchpad

Subcategory input:touchpad:

namedescriptiontypedefault
disable_while_typingdisables the touchpad while typingbooltrue
natural_scrollself-explanatoryboolfalse
clickfinger_behaviorself-explanatoryboolfalse
middle_button_emulationself-explanatoryboolfalse
tap-to-clickself-explanatorybooltrue
drag_lockenable dragging with drag lockboolfalse

A subcategory is a nested category:

input {
    # ...
    # ...

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

Doing input:touchpad { is invalid!

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

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
damage_entire_on_snapshot(deprecated: do not enable) Damage the entire monitor when rendering snapshots. Recommended with transformed displays. Do not use without transformed displays.boolfalse
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

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

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

More

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