--- obj: application website: https://hyprland.org/ repo: https://github.com/hyprwm/Hyprland arch-wiki: https://wiki.archlinux.org/title/Hyprland --- # hyprland A dynamic tiling Wayland compositor based on wlroots that doesn't sacrifice on its looks. ![Screenshot](./hyprland.webp) ## 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](https://wiki.hyprland.org/Configuring/Tearing). | 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](https://wayland.freedesktop.org/libinput/doc/latest/pointer-acceleration.html#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](https://wayland.freedesktop.org/libinput/doc/latest/pointer-acceleration.html#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](https://wayland.freedesktop.org/libinput/doc/latest/scrolling.html) | 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](https://wayland.freedesktop.org/libinput/doc/latest/middle-button-emulation.html) | 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](https://wayland.freedesktop.org/libinput/doc/latest/clickpad-softbuttons.html#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](https://wayland.freedesktop.org/libinput/doc/latest/tapping.html#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](https://github.com/ziishaned/learn-regex/blob/master/README.md). | 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 ``` ```ini 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: ```shell 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](https://wiki.hyprland.org/Configuring/Dispatchers/#list-of-dispatchers) 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](https://wiki.hyprland.org/Configuring/Dispatchers/#executing-with-rules)) | | 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](https://wiki.hyprland.org/Configuring/Binds/#global-keybinds) | name | | submap | Change the current mapping group. See [Submaps](https://wiki.hyprland.org/Configuring/Binds/#submaps) | `reset` or name | ### Window Rules #### Syntax ``` windowrule=RULE,WINDOW ``` - `RULE` is a [rule](https://wiki.hyprland.org/Configuring/Window-Rules/#rules) (and a param if applicable) - `WINDOW` is a [RegEx](https://en.wikipedia.org/wiki/Regular_expression), either: - plain [RegEx](../../tools/Regex.md) (for matching a window class); - `title:` followed by a [regex](../../tools/Regex.md) (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](https://wiki.hyprland.org/Configuring/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](https://wiki.hyprland.org/Configuring/Variables#variable_types) 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](https://wiki.hyprland.org/Configuring/Tearing). | ✓ | #### 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: ```sh 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: ```sh 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.: ```shell # 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](../../files/JSON.md) 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.: ```sh 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. ```sh 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](../utilities/Dunst.md), `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](https://wiki.hyprland.org/Useful-Utilities/Hyprland-desktop-portal) #### 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](Waybar.md) ### Wallpapers - [Hyprpaper](Hyprpaper.md) ### 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](https://github.com/hyprwm/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: ```sh pacman -S xdg-desktop-portal-hyprland ``` ### App Launchers - [Rofi](../utilities/Rofi.md) ### Automatically Mounting Using`udiskie` _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](https://github.com/coldfix/udiskie/wiki/installation) 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.