knowledge/technology/applications/desktops/hyprland.md

obj	website	repo	arch-wiki
application	https://hyprland.org/	https://github.com/hyprwm/Hyprland	https://wiki.archlinux.org/title/Hyprland

hyprland

A dynamic tiling Wayland compositor based on wlroots that doesn't sacrifice on its looks.

Configuration

The config is located in ~/.config/hypr/hyprland.conf.

Variables

Variable Types

type	description
int	integer
bool	boolean, true or false (yes or no, on or off, 0 or 1)
float	floating point number
color	color, rgba(b3ff1aee), rgb(b3ff1a)
vec2	vector with 2 values (float), seperated by a space (e.g 0 0 or -10.9 99.1)
MOD	a string modmask (e.g. SUPER or SUPERSHIFT or SUPER + SHIFT or SUPER and SHIFT or CTRL_SHIFT or empty for none)
str	a string

Sections

General

name	description	type	default
sensitivity	mouse sensitivity (legacy, may cause bugs if not 1, prefer input:sensitivity)	float	1.0
border_size	size of the border around windows	int	1
no_border_on_floating	disable borders for floating windows	bool	false
gaps_in	gaps between windows	int	5
gaps_out	gaps between windows and monitor edges	int	20
col.inactive_border	border color for inactive windows	gradient	0xffffffff
col.active_border	border color for the active window	gradient	0xff444444
col.nogroup_border	inactive border color for window that cannot be added to a group (see denywindowfromgroup dispatcher)	gradient	0xffffaaff
col.nogroup_border_active	active border color for window that cannot be added to a group	gradient	0xffff00ff
col.group_border	inactive (out of focus) group border color	gradient	0x66777700
col.group_border_active	active group border color	gradient	0x66ffff00
col.group_border_locked	inactive locked group border color	gradient	0x66775500
col.group_border_locked_active	active locked group border color	gradient	0x66ff5500
cursor_inactive_timeout	in seconds, after how many seconds of cursor’s inactivity to hide it. Set to 0 for never.	int	0
layout	which layout to use. (Available: dwindle, master)	str	dwindle
no_cursor_warps	if true, will not warp the cursor in many cases (focusing, keybinds, etc)	bool	false
no_focus_fallback	if true, will not fall back to the next available window when moving focus in a direction where no window was found	bool	false
apply_sens_to_raw	if on, will also apply the sensitivity to raw mouse output (e.g. sensitivity in games) NOTICE: really not recommended.	bool	false
resize_on_border	enables resizing windows by clicking and dragging on borders and gaps	bool	false
extend_border_grab_area	extends the area around the border where you can click and drag on, only used when general:resize_on_border is on.	int	15
hover_icon_on_border	show a cursor icon when hovering over borders, only used when general:resize_on_border is on.	bool	true
allow_tearing	master switch for allowing tearing to occur. See the Tearing page.	bool	false

Decoration

name	description	type	default
rounding	rounded corners’ radius (in layout px)	int	0
active_opacity	opacity of active windows. (0.0 - 1.0)	float	1.0
inactive_opacity	opacity of inactive windows. (0.0 - 1.0)	float	1.0
fullscreen_opacity	opacity of fullscreen windows. (0.0 - 1.0)	float	1.0
drop_shadow	enable drop shadows on windows	bool	true
shadow_range	Shadow range (“size”) in layout px	int	4
shadow_render_power	(1 - 4), in what power to render the falloff (more power, the faster the falloff)	int	3
shadow_ignore_window	if true, the shadow will not be rendered behind the window itself, only around it.	bool	true
col.shadow	shadow’s color. Alpha dictates shadow’s opacity.	color	0xee1a1a1a
col.shadow_inactive	inactive shadow color. (if not set, will fall back to col.shadow)	color	unset
shadow_offset	shadow’s rendering offset.	vec2	[0, 0]
shadow_scale	shadow’s scale. 0.0 - 1.0	float	1.0
dim_inactive	enables dimming of inactive windows	bool	false
dim_strength	how much inactive windows should be dimmed, 0.0 - 1.0	float	0.5
dim_special	how much to dim the rest of the screen by when a special workspace is open. 0.0 - 1.0	float	0.2
dim_around	how much the dimaround window rule should dim by. 0.0 - 1.0	float	0.4
screen_shader	a path to a custom shader to be applied at the end of rendering. See examples/screenShader.frag for an example.	str	Empty

Blur

Subcategory decoration:blur:

name	description	type	default
enabled	enable kawase window background blur	bool	true
size	blur size (distance)	int	8
passes	the amount of passes to perform	int	1
ignore_opacity	make the blur layer ignore the opacity of the window	bool	false
new_optimizations	whether to enable further optimizations to the blur. Recommended to leave on, as it will massively improve performance.	bool	true
xray	if 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.	bool	false
noise	how much noise to apply. 0.0 - 1.0	float	0.0117
contrast	contrast modulation for blur. 0.0 - 2.0	float	0.8916
brightness	brightness modulation for blur. 0.0 - 2.0	float	0.8172
special	whether to blur behind the special workspace (note: expensive)	bool	false

Animations

name	description	type	default
enabled	enable animations	bool	true

Input

name	description	type	default
kb_model	Appropriate XKB keymap parameter. See the note below.	str	Empty
kb_layout	Appropriate XKB keymap parameter	str	us
kb_variant	Appropriate XKB keymap parameter	str	Empty
kb_options	Appropriate XKB keymap parameter	str	Empty
kb_rules	Appropriate XKB keymap parameter	str	Empty
kb_file	If you prefer, you can use a path to your custom .xkb file.	str	Empty
numlock_by_default	Engage numlock by default.	bool	false
repeat_rate	The repeat rate for held-down keys, in repeats per second.	int	25
repeat_delay	Delay before a held-down key is repeated, in milliseconds.	int	600
sensitivity	Sets the mouse input sensitivity. Value will be clamped to the range -1.0 to 1.0. libinput#pointer-acceleration	float	0.0
accel_profile	Sets the cursor acceleration profile. Can be one of adaptive, flat. Can also be custom, see below. Leave empty to use libinput’s default mode for your input device. libinput#pointer-acceleration	str	Empty
force_no_accel	Force 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.	bool	false
left_handed	Switches RMB and LMB	bool	false
scroll_method	Sets the scroll method. Can be one of 2fg (2 fingers), edge, on_button_down, no_scroll. libinput#scrolling	str	Empty
scroll_button	Sets 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.	int	0
scroll_button_lock	If the scroll button lock is enabled, the button does not need to be held down. Pressing and releasing the button once enables the button lock, the button is now considered logically held down. Pressing and releasing the button a second time logically releases the button. While the button is logically held down, motion events are converted to scroll events.	bool	0
natural_scroll	Inverts scrolling direction. When enabled, scrolling moves content directly instead of manipulating a scrollbar.	bool	false
follow_mouse	(0/1/2/3) Specify if and how cursor movement should affect window focus. See the note below.	int	1
mouse_refocus	If disabled and follow_mouse=1 then mouse focus will not switch to the hovered window unless the mouse crosses a window boundary.	bool	true
float_switch_override_focus	If 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.	int	1

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.

Touchpad

Subcategory input:touchpad:

name	description	type	default
disable_while_typing	Disable the touchpad while typing.	bool	true
natural_scroll	Inverts scrolling direction. When enabled, scrolling moves content directly instead of manipulating a scrollbar.	bool	false
scroll_factor	Multiplier applied to the amount of scroll movement.	float	1.0
middle_button_emulation	Sending 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-emulation	bool	false
tap_button_map	Sets the tap button mapping for touchpad button emulation. Can be one of lrm (default) or lmr (Left, Middle, Right Buttons).	str	Empty
clickfinger_behavior	Button 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-behavior	bool	false
tap-to-click	Tapping on the touchpad with 1, 2, or 3 fingers will send LMB, RMB, and MMB respectively.	bool	true
drag_lock	When enabled, lifting the finger off for a short time while dragging will not drop the dragged item. libinput#tap-and-drag	bool	false
tap-and-drag	Sets the tap and drag mode for the touchpad	bool	false

Gestures

name	description	type	default
workspace_swipe	enable workspace swipe gesture	bool	false
workspace_swipe_fingers	how many fingers for the gesture	int	3
workspace_swipe_distance	in px, the distance of the gesture	int	300
workspace_swipe_invert	invert the direction	bool	true
workspace_swipe_min_speed_to_force	minimum speed in px per timepoint to force the change ignoring cancel_ratio. Setting to 0 will disable this mechanic.	int	30
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)	float	0.5
workspace_swipe_create_new	whether a swipe right on the last workspace should create a new one.	bool	true
workspace_swipe_direction_lock	if enabled, switching direction will be locked when you swipe past the direction_lock_threshold.	bool	true
workspace_swipe_direction_lock_threshold	in px, the distance to swipe before direction lock activates.	int	10
workspace_swipe_forever	if enabled, swiping will not clamp at the neighboring workspaces but continue to the further ones.	bool	false
workspace_swipe_numbered	if enabled, swiping will swipe on consecutive numbered workspaces.	bool	false
workspace_swipe_use_r	if enabled, swiping will use the r prefix instead of the m prefix for finding workspaces. (requires disabled workspace_swipe_numbered)	bool	false

Misc

name	description	type	default
disable_hyprland_logo	disables the random hyprland logo / anime girl background. :(	bool	false
disable_splash_rendering	disables the hyprland splash rendering. (requires a monitor reload to take effect)	bool	false
force_hypr_chan	makes the background always have hypr-chan, the hyprland mascot	bool	false
force_default_wallpaper	Enforce any of the 3 default wallpapers. Setting this to 0 disables the anime background. -1 means “random”	int	-1
vfr	controls the VFR status of hyprland. Heavily recommended to leave on true to conserve resources.	bool	true
vrr	controls the VRR (Adaptive Sync) of your monitors. 0 - off, 1 - on, 2 - fullscreen only	int	0
mouse_move_enables_dpms	If DPMS is set to off, wake up the monitors if the mouse moves.	bool	false
key_press_enables_dpms	If DPMS is set to off, wake up the monitors if a key is pressed.	bool	false
always_follow_on_dnd	Will make mouse focus follow the mouse when drag and dropping. Recommended to leave it enabled, especially for people using focus follows mouse at 0.	bool	true
layers_hog_keyboard_focus	If true, will make keyboard-interactive layers keep their focus on mouse move (e.g. wofi, bemenu)	bool	true
animate_manual_resizes	If true, will animate manual window resizes/moves	bool	false
animate_mouse_windowdragging	If true, will animate windows being dragged by mouse, note that this can cause weird behavior on some curves	bool	false
disable_autoreload	If true, the config will not reload automatically on save, and instead needs to be reloaded with hyprctl reload. Might save on battery.	bool	false
enable_swallow	Enable window swallowing	bool	false
swallow_regex	The class regex to be used for windows that should be swallowed (usually, a terminal). To know more about the list of regex which can be used use this cheatsheet.	str	Empty
swallow_exception_regex	The title regex to be used for windows that should not be swallowed by the windows specified in swallow_regex (e.g. wev). The regex is matched against the parent (e.g. Kitty) window’s title on the assumption that it changes to whatever process it’s running.	str	Empty
focus_on_activate	Whether Hyprland should focus an app that requests to be focused (an activate request)	bool	false
no_direct_scanout	Disables direct scanout. Direct scanout attempts to reduce lag when there is only one fullscreen application on a screen (e.g. game). It is also recommended to set this to true if the fullscreen application shows graphical glitches.	bool	true
hide_cursor_on_touch	Hides the cursor when the last input was a touch input until a mouse input is done.	bool	true
mouse_move_focuses_monitor	Whether mouse moving into a different monitor should focus it	bool	true
suppress_portal_warnings	disables warnings about incompatible portal implementations.	bool	false
render_ahead_of_time	[Warning: buggy] starts rendering before your monitor displays a frame in order to lower latency	bool	false
render_ahead_safezone	how many ms of safezone to add to rendering ahead of time. Recommended 1-2.	int	1
cursor_zoom_factor	the factor to zoom by around the cursor. AKA. Magnifying glass. Minimum 1.0 (meaning no zoom)	float	1.0
cursor_zoom_rigid	whether the zoom should follow the cursor rigidly (cursor is always centered if it can be) or loosely	bool	false
allow_session_lock_restore	if true, will allow you to restart a lockscreen app in case it crashes (red screen of death)	bool	false
group_insert_after_current	whether new windows in a group spawn after current or at group tail	bool	true
group_focus_removed_window	whether Hyprland should focus on the window that has just been moved out of the group	bool	true
groupbar_scrolling	whether scrolling in the groupbar changes group active window	bool	true
render_titles_in_groupbar	whether to render titles in the group bar decoration	bool	true
groupbar_titles_font_size	font size for the above	int	8
groupbar_gradients	whether to draw gradients under the titles of the above	bool	true
groupbar_text_color	controls the group bar text color	color	0xffffffff
background_color	change the background color. (requires enabled disable_hyprland_logo)	color	0x111111
close_special_on_empty	close the special workspace if the last window is removed	bool	true
new_window_takes_over_fullscreen	if there is a fullscreen window, whether a new tiled window opened should replace the fullscreen one or stay behind. 0 - behind, 1 - takes over, 2 - unfullscreen the current fullscreen window	int	0

Keywords

Executing

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

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

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.

Setting the environment

The env keyword works just like exec-once, meaning it will only fire once on Hyprland’s launch.

You can use the env keyword to set environment variables at Hyprland’s start, e.g.:

env = XCURSOR_SIZE,24

env = QT_QPA_PLATFORM,wayland

Monitor

General

The general config of a monitor looks like this

monitor=name,resolution,position,scale

A common example:

monitor=DP-1,1920x1080@144,0x0,1

will tell Hyprland to make the monitor on DP-1 a 1920x1080 display, at 144Hz, 0x0 off from the top left corner, with a scale of 1 (unscaled).

To list available monitors:

hyprctl monitors

Monitors are positioned on a virtual “layout”. The position is the position of said display in the layout. (calculated from the top-left corner)

For example:

monitor=DP-1, 1920x1080, 0x0, 1
monitor=DP-2, 1920x1080, 1920x0, 1

will tell hyprland to make DP-1 on the left of DP-2, while

monitor=DP-1, 1920x1080, 1920x0, 1
monitor=DP-2, 1920x1080, 0x0, 1

will tell hyprland to make DP-1 on the right.

The position is calculated with the scaled (and transformed) resolution, meaning if you want your 4K monitor with scale 2 to the left of your 1080p one, you’d use the position 1920x0 for the second screen. (3840 / 2) If the monitor is also rotated 90 degrees (vertical) you’d use 1080x0.

Leaving the name empty will define a fallback rule to use when no other rules match.

You can use preferred as a resolution to use the display’s preferred size, and auto as a position to let Hyprland decide on a position for you.

You can also use auto as a scale to let Hyprland decide on a scale for you. These depend on the PPI of the monitor.

Recommended rule for quickly plugging in random monitors:

monitor=,preferred,auto,1

Will make any monitor that was not specified with an explicit rule automatically placed on the right of the other(s) with its preferred resolution.

Disabling a monitor

To disable a monitor, use

monitor=name,disable

Mirrored displays

If you want to mirror a display, add a ,mirror,[NAME] at the end of the monitor rule, examples:

monitor=DP-3,1920x1080@60,0x0,1,mirror,DP-2
monitor=,preferred,auto,1,mirror,DP-1

Please remember that mirroring displays will not “re-render” everything for your second monitor, so if mirroring a 1080p screen onto a 4K one, the resolution will still be 1080p on the 4K display. This also means squishing and stretching will occur on non-matching resolutions.

Rotating

If you want to rotate a monitor, add a ,transform,X at the end of the monitor rule, where X corresponds to a transform number, e.g.:

monitor=eDP-1,2880x1800@90,0x0,1,transform,1

Transform list:

normal (no transforms) -> 0
90 degrees -> 1
180 degrees -> 2
270 degrees -> 3
flipped -> 4
flipped + 90 degrees -> 5
flipped + 180 degrees -> 6
flipped + 270 degrees -> 7

Binds

Basic

bind=MODS,key,dispatcher,params

for example,

bind=SUPER_SHIFT,Q,exec,firefox

will bind opening firefox to SUPER + SHIFT + Q

For binding keys without a modkey, leave it empty:

bind=,Print,exec,grim

Switches

Useful for binding e.g. the lid close/open event:

# trigger when the switch is toggled
bindl=,switch:[switch name],exec,swaylock
# trigger when the switch is turning on
bindl=,switch:on:[switch name],exec,hyprctl keyword monitor "eDP-1, 2560x1600, 0x0, 1"
# trigger when the switch is turning off
bindl=,switch:off:[switch name],exec,hyprctl keyword monitor "eDP-1, disable"

check out your switches in hyprctl devices.

Bind flags

bind supports flags in this format:

bind[flags]=...

e.g.:

bindrl=MOD,KEY,exec,amongus

Flags:

l -> locked, aka. works also when an input inhibitor (e.g. a lockscreen) is active.
r -> release, will trigger on release of a key.
e -> repeat, will repeat when held.
n -> non-consuming, key/mouse events will be passed to the active window in addition to triggering the dispatcher.
m -> mouse, see below
t -> transparent, cannot be shadowed by other binds.

Example Usage:

# Example volume button that allows press and hold, volume limited to 150%
binde=, XF86AudioRaiseVolume, exec, wpctl set-volume -l 1.5 @DEFAULT_AUDIO_SINK@ 5%+

# Example volume button that will activate even while an input inhibitor is active
bindl=, XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-

# Start wofi opens wofi on first press, closes it on second
bindr=SUPER, SUPER_L, exec, pkill wofi || wofi

# See Mouse Binds section for bindm usage

Global Keybinds

Yes, you heard this right, Hyprland does support global keybinds for ALL apps, including OBS, Discord, Firefox, etc.

See the pass dispatcher for keybinds.

Let’s take OBS as an example: the “Start/Stop Recording” keybind is set to SUPER + F10, and you want to make it work globally.

Simply add to your config and you’re done

bind = SUPER,F10,pass,^(com\.obsproject\.Studio)$

Submaps

If you want keybind submaps, also known as modes or groups, for example if you press ALT + R, you can enter a “resize” mode, resize with arrow keys, and leave with escape, do it like this:

# will switch to a submap called resize
bind=ALT,R,submap,resize

# will start a submap called "resize"
submap=resize

# sets repeatable binds for resizing the active window
binde=,right,resizeactive,10 0
binde=,left,resizeactive,-10 0
binde=,up,resizeactive,0 -10
binde=,down,resizeactive,0 10

# use reset to go back to the global submap
bind=,escape,submap,reset 

# will reset the submap, meaning end the current one and return to the global one
submap=reset

# keybinds further down will be global again...

IMPORTANT: do not forget a keybind to reset the keymap while inside it! (In this case, escape)

Dispatchers

Parameter explanation

Param type	Description
window	a window. Any of the following: Class regex, title: and a title regex, pid: and the pid, address: and the address
workspace	see below.
direction	l r u d left right up down
monitor	One of: direction, ID, name, current, relative (e.g. +1 or -1)
resizeparams	relative pixel delta vec2 (e.g. 10 -10), optionally a percentage of the window size (e.g. 20 25%) or exact followed by an exact vec2 (e.g. exact 1280 720), optionally a percentage of the screen size (e.g. exact 50% 50%)
floatvalue	a relative float delta (e.g -0.2 or +0.2) or exact followed by a the exact float value (e.g. exact 0.5)
workspaceopt	see below.
zheight	top or bottom

List of Dispatchers

Dispatcher	Description	Params
exec	executes a shell command	command (supports rules, see below)
execr	executes a raw shell command (will not append any additional envvars like exec does, does not support rules)	command
pass	passes the key (with mods) to a specified window. Can be used as a workaround to global keybinds not working on Wayland.	window
killactive	closes (not kills) the active window	none
closewindow	closes a specified window	window
workspace	changes the workspace	workspace
movetoworkspace	moves the focused window to a workspace	workspace OR workspace,window for a specific window
movetoworkspacesilent	same as above, but doesnt switch to the workspace	workspace OR workspace,window for a specific window
togglefloating	toggles the current window’s floating state	left empty / active for current, or window for a specific window
fullscreen	toggles the focused window’s fullscreen state	0 - fullscreen (takes your entire screen), 1 - maximize (keeps gaps and bar(s))
fakefullscreen	toggles the focused window’s internal fullscreen state without altering the geometry	none
dpms	sets all monitors’ DPMS status. Do not use with a keybind directly.	on, off, or toggle. For specific monitor add monitor name after a space
pin	pins a window (i.e. show it on all workspaces) note: floating only	left empty / active for current, or window for a specific window
movefocus	moves the focus in a direction	direction
movewindow	moves the active window in a direction or to a monitor	direction or mon: and a monitor
swapwindow	swaps the active window with another window in the given direction	direction
centerwindow	center the active window note: floating only	none (for monitor center) or 1 (to respect monitor reserved area)
resizeactive	resizes the active window	resizeparams
moveactive	moves the active window	resizeparams
resizewindowpixel	resizes a selected window	resizeparams,window, e.g. 100 100,^(kitty)$
movewindowpixel	moves a selected window	resizeparams,window
cyclenext	focuses the next window on a workspace	none (for next) or prev (for previous)
swapnext	swaps the focused window with the next window on a workspace	none (for next) or prev (for previous)
focuswindow	focuses the first window matching	window
focusmonitor	focuses a monitor	monitor
splitratio	changes the split ratio	floatvalue
toggleopaque	toggles the current window to always be opaque. Will override the opaque window rules.	none
movecursortocorner	moves the cursor to the corner of the active window	direction, 0 - 3, bottom left - 0, bottom right - 1, top right - 2, top left - 3
movecursor	moves the cursor to a specified position	x,y
workspaceopt	toggles a workspace option for the active workspace.	workspaceopt
renameworkspace	rename a workspace	id name, e.g. 2 work
exit	exits the compositor with no questions asked.	none
forcerendererreload	forces the renderer to reload all resources and outputs	none
movecurrentworkspacetomonitor	Moves the active workspace to a monitor	monitor
moveworkspacetomonitor	Moves a workspace to a monitor	workspace and a monitor separated by a space
swapactiveworkspaces	Swaps the active workspaces between two monitors	two monitors separated by a space
bringactivetotop	Deprecated in favor of alterzorder. Brings the current window to the top of the stack	none
alterzorder	Modify the window stack order of the active or specified window. Note: this cannot be used to move a floating window behind a tiled one.	zheight[,window]
togglespecialworkspace	toggles a special workspace on/off	none (for the first) or name for named (name has to be a special workspace’s name)
focusurgentorlast	Focuses the urgent window or the last window	none
togglegroup	toggles the current active window into a group	none
changegroupactive	switches to the next window in a group.	b - back, f - forward, or index start at 1
focuscurrentorlast	Switch focus from current to previously focused window	none
lockgroups	Locks the groups (all groups will not accept new windows)	lock for locking, unlock for unlocking, toggle for toggle
lockactivegroup	Lock the focused group (the current group will not accept new windows or be moved to other groups)	lock for locking, unlock for unlocking, toggle for toggle
moveintogroup	Moves the active window into a group in a specified direction. No-op if there is no group in the specified direction.	direction
moveoutofgroup	Moves the active window out of a group. No-op if not in a group	none
movewindoworgroup	Behaves as moveintogroup if there is a group in the given direction. Behaves as moveoutofgroup if there is no group in the given direction relative to the active group. Otherwise behaves like movewindow.	direction
movegroupwindow	Swaps the active window with the next or previous in a group	b for back, anything else for forward
denywindowfromgroup	Prohibit the active window from becoming or being inserted into group	on, off or, toggle
setignoregrouplock	Temporarily enable or disable binds:ignore_group_lock	on, off, or toggle
global	Executes a Global Shortcut using the GlobalShortcuts portal. See here	name
submap	Change the current mapping group. See Submaps	reset or name

Window Rules

Syntax

windowrule=RULE,WINDOW

• RULE is a rule (and a param if applicable)
• WINDOW is a RegEx, either:
  • plain RegEx (for matching a window class);
  • title: followed by a regex (for matching a window’s title)

Rules

Rule	Description	Dynamic
float	floats a window
tile	tiles a window
fullscreen	fullscreens a window
fakefullscreen	fakefullscreens a window
maximize	maximizes a window
nofullscreenrequest	prevents windows from requesting fullscreen mode, you can still manually toggle fullscreen.
nomaximizerequest	prevents windows from requesting maximized mode, you can still manually toggle maximize.
move [x] [y]	moves a floating window (x,y -> int or %, e.g. 20% or 100. You are also allowed to do 100%- for the right/bottom anchor, e.g. 100%-20). Additionally, you can also do cursor [x] [y] where x and y are either pixels or percent. Percent is calculated from the window’s size. Specify onscreen before other parameters to force the window into the screen (e.g. move onscreen cursor 50% 50%)
size [x] [y]	resizes a floating window (x,y -> int or %, e.g. 20% or 100)
minsize [x] [y]	sets the minimum size on creation (x,y -> int)
maxsize [x] [y]	sets the maximum size on creation (x,y -> int)
center ([opt])	if the window is floating, will center it on the monitor. Set opt as 1 to respect monitor reserved area
pseudo	pseudotiles a window
monitor [id]	sets the monitor on which a window should open. id can be either id or name (either e.g. 1 or e.g. DP-1)
workspace [w]	sets the workspace on which a window should open (for workspace syntax, see dispatchers->workspaces). You can also make [w] to unset, will unset all previous workspace rules applied to this window. You can also add silent after the workspace to make the window open silently.
opacity [a]	additional opacity multiplier. Options for a: float -> sets an opacity OR float float -> sets activeopacity and inactiveopacity respectively. You can also add override after an opacity to make it override instead of a multiplier. (e.g. 1.0 override 0.5 override)	✓
opaque	forces the window to be opaque (can be toggled with the toggleopaque dispatcher)	✓
forcergbx	makes hyprland ignore the alpha channel of all the window’s surfaces, effectively making it actually, fully 100% opaque	✓
animation [style] ([opt])	forces an animation onto a window, with a selected opt. Opt is optional.	✓
rounding [x]	forces the application to have X pixels of rounding, ignoring the set default (in decoration:rounding). Has to be an int.	✓
noblur	disables blur for the window	✓
nofocus	disables focus to the window
noinitialfocus	disables the initial focus to the window
noborder	disables borders for the window	✓
bordersize [size]	sets the border size	✓
nodim	disables window dimming for the window	✓
noshadow	disables shadows for the window	✓
forceinput	forces an XWayland window to receive input, even if it requests not to do so. (Might fix issues like e.g. Game Launchers not receiving focus for some reason)
windowdance	forces an XWayland window to never refocus, used for games/applications like Rhythm Doctor
pin	pins the window (i.e. show it on all workspaces) note: floating only
noanim	disables the animations for the window	✓
keepaspectratio	forces aspect ratio when resizing window with the mouse	✓
bordercolor [c]	force the bordercolor of the window. Options for c: color -> sets the active border color OR color color -> sets the active and inactive border color of the window. See variables->colors for color definition.	✓
idleinhibit [mode]	sets an idle inhibit rule for the window. If active, apps like swayidle will not fire. Modes: none, always, focus, fullscreen
unset	removes all previously set rules for the given parameters. Please note it has to match EXACTLY.
nomaxsize	removes max size limitations. Especially useful with windows that report invalid max sizes (e.g. winecfg)
dimaround	dims everything around the window . Please note this rule is meant for floating windows and using it on tiled ones may result in strange behavior.	✓
stayfocused	forces focus on the window as long as it’s visible
xray [on]	sets blur xray mode for the window (0 for off, 1 for on, unset for default)	✓
group [options]	set window group properties. See the note below.
immediate	forces the window to allow to be torn. See the Tearing page.	✓

Window Rules V2

In V2, you are allowed to match multiple variables.

the RULE field is unchanged, but in the WINDOW field, you can put regexes for multiple values like so:

windowrulev2 = float,class:(kitty),title:(kitty)

In the case of dynamic window titles such as browser windows keep in mind how powerful regex is.
for example a window rule of: windowrule=opacity 0.3 override 0.3 override,title:(.*)(- Youtube)$ will match any window that contains a string of “- Youtube” after any other text. This could be multiple browser windows or other applications that contain the string for any reason.
for the windowrulev2 = float,class:(kitty),title:(kitty) example, the class:(kitty) WINDOW field is what keeps the window rule specific to kitty terminals.

For now, the supported fields are:

class - class regex 
title - title regex
xwayland - 0/1
floating - 0/1
fullscreen - 0/1
pinned - 0/1
workspace - id or name: and name

Tearing

To enable tearing:

• Set general:allow_tearing to true. This is a “master toggle”
• Add env = WLR_DRM_NO_ATOMIC,1 to your Hyprland config. This disables the usage of a newer kernel DRM API that doesn’t support tearing yet.
• Add an immediate windowrule to your game of choice. This makes sure that Hyprland will tear it.

Please note that tearing will only be in effect when the game is in fullscreen and the only thing visible on the screen.

Example snippet:

general {
    allow_tearing = true
}

env = WLR_DRM_NO_ATOMIC,1

windowrulev2 = immediate, class:^(cs2)$

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.

Dispatch

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.

Examples:

hyprctl dispatch exec kitty
hyprctl dispatch -- exec kitty --single-instance
hyprctl dispatch pseudo x

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

Keyword

issue a keyword to call a config keyword dynamically.

Examples:

hyprctl keyword bind SUPER,O,pseudo
hyprctl keyword general:border_size 10
hyprctl keyword monitor DP-3,1920x1080@144,0x0,1

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

Reload

issue a reload to force reload the config.

output

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.

e.g.:

# 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

Info

These commands let you gather information about your Hyprland session. Hyprctl can output JSON with the -j flag.

Command	Description
version	prints the hyprland version, meaning flags, commit and branch of build
monitors	lists active outputs with their properties, monitors all lists active and inactive outputs
workspaces	lists all workspaces with their properties
activeworkspace	gets the active workspace and its properties
workspacerules	gets the list of defined workspace rules
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 and its properties
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 info about animations and beziers
instances	lists all running instances of hyprland with their info
layouts	lists all layouts available

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

Batch

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

e.g.

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

; separates the commands

Multi GPU

If your host machine uses multiple GPUs, you may want to primarily use one GPU for rendering all the elements for Hyprland including windows, animations, and another for hardware acceleration for certain applications, etc.

This setup is very common in the likes of gaming laptops, GPU-passthrough (without VFIO) capable hosts, and if you have multiple GPUs in general.

Detecting GPUs

Upon running lspci | grep -E 'VGA|3D', One can list all the video devices available.

01:00.0 VGA compatible controller: NVIDIA Corporation TU117M [GeForce GTX 1650 Mobile / Max-Q] (rev a1)
06:00.0 VGA compatible controller: Advanced Micro Devices, Inc. [AMD/ATI] Cezanne [Radeon Vega Series / Radeon Vega Mobile Series] (rev c6)

Here it is clear that 2 GPUs are available, the dedicated NVIDIA GTX 1650 Mobile / Max-Q and the integrated AMD Cezanne Radeon Vega Series GPU.

Now, run ls -l /dev/dri/by-path

 total 0
lrwxrwxrwx 1 root root  8 Jul 14 15:45 pci-0000:01:00.0-card -> ../card0
lrwxrwxrwx 1 root root 13 Jul 14 15:45 pci-0000:01:00.0-render -> ../renderD128
lrwxrwxrwx 1 root root  8 Jul 14 15:45 pci-0000:06:00.0-card -> ../card1
lrwxrwxrwx 1 root root 13 Jul 14 15:45 pci-0000:06:00.0-render -> ../renderD129

So from the above outputs, we can match the bus IDs and determine that NVIDIA is card0 and AMD is card1.

Telling Hyprland which GPU to use

After determining which “card” belongs to which GPU, we now have to tell Hyprland the GPU we want to use primarily.

It is generally a good idea for laptops to use the integrated GPU as the primary renderer as this preserves battery life and is practically indistinguishable from using the dedicated GPU on modern systems in most cases. Hyprland can be run on integrated GPUs just fine. The same principle applies for desktop setups with a lower and higher power rating GPUs respectively.

We can do so by using the WLR_DRM_DEVICES variable.

Add the following template to hyprland.conf

env = WLR_DRM_DEVICES,/dev/dri/cardN

For our case, we want to use card1 primarily and use it to render stuff.

env = WLR_DRM_DEVICES,/dev/dri/card1:/dev/dri/card0

Here, we tell Hyprland to set priorities. If card1 isn’t available for whatever reason, use card0. So if the AMD GPU isn’t available, use NVIDIA. The colon is for setting priorities, essentially.

You should now be able to use an integrated GPU for for lighter GPU loads, including Hyprland.

Useful Utilities

Must Haves

This page documents software that is critical / very important to have running for a smooth Wayland / Hyprland experience.

DEs like KDE / Gnome will do this automatically, Hyprland will not (because you might want to use something else)

Notification Daemon

Starting method: most likely manual (exec-once)

Many apps (e.g. Discord) may freeze without one running.

Use e.g. Dunst, mako, etc.

Pipewire

Starting method: automatic

Pipewire is not necessarily required, but screensharing will not work without it.

Install pipewire and wireplumber (not pipewire-media-session)

XDG Desktop Portal

Starting method: Automatic on Systemd, manual otherwise

XDG Desktop Portal handles a lot of stuff for your desktop, like file pickers, screensharing, etc.

See The Hyprland Desktop Portal Page

Authentication Agent

Starting method: manual (exec-once)

Authentication agents are the things that pop up a window asking you for a password whenever an app wants to elevate its privileges.

Our recommendation is the KDE one. For arch, it’s polkit-kde-agent.

You can autostart it with exec-once=/usr/lib/polkit-kde-authentication-agent-1. On some distributions you might have to use a different path /usr/libexec/polkit-kde-authentication-agent-1.

On other distributions that use a more recent version, such as Gentoo, it may be necessary to use exec-once=/usr/lib64/libexec/polkit-kde-authentication-agent-1 instead.

Qt Wayland Support

Starting method: none (just a library)

Install qt5-wayland and qt6-wayland.

Status Bars

• Waybar

Wallpapers

• Hyprpaper

Hyprland Desktop Portal

An XDG Desktop Portal (later called XDP) is a program that lets other applications communicate swiftly with the compositor through D-Bus.

It’s used for stuff like e.g. opening file pickers, screen sharing.

On Wayland, it also requires an implementation. For Hyprland, you’d usually use xdg-desktop-portal-wlr (later called XDPW)

Unfortunately, due to various reasons the -wlr portal is inferior to the KDE or Gnome ones.

In order to bridge the gap, Hyprland has its own fork of XDPW that has more features, called xdg-desktop-portal-hyprland. (later called XDPH)

XDPH doesn’t implement a file picker. For that, I recommend installing xdg-desktop-portal-gtk alongside XDPH.

Install:

pacman -S xdg-desktop-portal-hyprland

App Launchers

• Rofi

Automatically Mounting Usingudiskie

Starting method: manual (’exec-once')

USB Mass storage devices, like thumb drives, mobile phones, digital cameras, etc. do not mount automatically to the file system.

We generally have to manually mount it, often using root and umount to do so.

Many popular DEs automatically handle this by using udisks2 wrappers.

udiskie is a udisks2 front-end that allows to manage removable media such as CDs or flash drives from userspace.

Install udiskie via your repositories, or build manually

Head over to your ~/.config/hypr/hyprland.conf and add the following lines:

exec-once = udiskie &

What this does is launches udiskie and & argument launches it in the background.