hyprwm
/
hyprland-wiki
mirror of https://github.com/hyprwm/hyprland-wiki.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

added pages

This commit is contained in:
Vaxry 2022-08-12 20:46:36 +02:00
parent 5861db0876
commit 24a554876b
24 changed files with 2490 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -1,2 +1,3 @@
# hyprland-wiki
The Hyprland Wiki Pages, automatically synced with the website.
# Hyprland Wiki
Welcome to the Hyprland Wiki. Here we store the Wiki Pages. Those are automatically updated on the website whenever a change occurs, within a reasonable timeframe.

836
pages/Configuring/Advanced-config.md Normal file
View File

@ -0,0 +1,836 @@
# Advanced config
### If you skipped the "Basic Config" page because you think you are the best, please check the Basic Config first. It documents configuration not mentioned here.
this page documents all of the more advanced config options. Binds, curves,
execs, etc.
Please remember, that for ALL arguments separated by a comma, if you want to leave one of them empty, you cannot reduce the number of commas, *unless told otherwise in a specific section*:
```
three_param_keyword=A,B,C # OK
three_param_keyword=A,C # NOT OK
three_param_keyword=A,,C # OK
```
# Monitors
```
monitor=name,res,offset,scale
```
for 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 beginning and a scale of 1.
Please use the offset for its intended purpose before asking stupid questions
about "fixing" monitors being mirrored.
Please remember the offset is calculated with the scaled resolution, meaning if
you want your 4K monitor with scale 2 to the left of your 1080p one, you'd use
the offset `1920x0` for the second screen. (3840 / 2)
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 an offset to let Hyprland decide on an offset for you.
Recommended rule for easy and quick plugging in of random monitors:
```
monitor=,preferred,auto,1
```
Will make any monitor that was not specified with an explicit rule automatically placed in a sensible location with its preferred resolution.
To disable a monitor, use
```
monitor=name,disable
```
If your workflow requires custom reserved area, you can add it with
```
monitor=name,addreserved,TOP,BOTTOM,LEFT,RIGHT
```
Where `TOP` `BOTTOM` `LEFT` `RIGHT` are integers in pixels of the reserved area
to add. This does stack on top of the calculated one, (e.g. bars) but you may
only use one of these rules per monitor in the config.
```
workspace=name,number
```
for example:
```
workspace=DP-1,1
```
will tell Hyprland to make the default workspace on DP-1 a number 1.
If you want to rotate a monitor, use
```
monitor=NAME,transform,TRANSFORM
```
where `NAME` is the name, and `TRANSFORM` is an integer, from 0 to 7,
corresponding to your transform of choice.
***Important!*** This keyword **MUST** be _after_ your `monitor=` keyword with
the resolution, etc.
```
WL_OUTPUT_TRANSFORM_NORMAL = 0
WL_OUTPUT_TRANSFORM_90 = 1
WL_OUTPUT_TRANSFORM_180 = 2
WL_OUTPUT_TRANSFORM_270 = 3
WL_OUTPUT_TRANSFORM_FLIPPED = 4
WL_OUTPUT_TRANSFORM_FLIPPED_90 = 5
WL_OUTPUT_TRANSFORM_FLIPPED_180 = 6
WL_OUTPUT_TRANSFORM_FLIPPED_270 = 7
```
# Binds
```
bind=MOD,key,dispatcher,params
```
for example,
```
bind=SUPERSHIFT,Q,exec,firefox
```
will bind opening firefox to SUPER+SHIFT+Q
Please note that `SHIFT` modifies the key names, so for example
```
bind=SHIFT,1,anything,
```
will not work, because when you press SHIFT+1, on your screen you won't get a 1,
you'll get a !
Common overwrites:
```
1 -> exclam
2 -> at
3 -> numbersign
4 -> dollar
5 -> percent
6 -> asciicircum
7 -> ampersand
8 -> asterisk
9 -> parenleft
0 -> parenright
- -> underscore
= -> plus
```
*(Overwrites may vary on different keymaps)*
See the
[xkbcommon-keysyms.h header](https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h)
for all the keysyms. The name you should use is the one after XKB_KEY\_, written
in all lowercase.
If you are unsure of what your key's name is, or what it shifts into, you can
use `xev` or `wev` to find that information.
If you want to bind by a keycode, you can just input it in the KEY position,
e.g.:
```
bind=SUPER,28,exec,amongus
```
Will bind SUPER+T. (T is keycode 28.) - You can also use `xev` or `wev` to find
keycodes.
You can also unbind with `unbind`, e.g.:
```
unbind=SUPER,O
```
May be useful for dynamic keybindings with `hyprctl`.
You can also bind mouse buttons, by prefacing the mouse keycode with `mouse:`,
for example:
```
bind=SUPER,mouse:272,exec,amongus
```
will bind it to SUPER+LMB.
For binding only modkeys, you need to use the TARGET modmask (with the activating mod) and the `r` flag, e.g.:
```
bindr=SUPERALT,Alt_L,exec,amongus
```
## 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 is active
r -> release, will trigger on release of a key
e -> repeat, will repeat when held.
```
## Binding mods
You can bind a mod alone like this:
```
bindr=ALT,Alt_L,exec,amongus
```
## General dispatcher list:
Please keep in mind some layout-specific dispatchers will be listed in the layout pages (See the sidebar)
### exec
executes a shell command
**params**: command
### pass
passes the key (with mods) to a specified window. Can be used as a workaround to
global keybinds not working on Wayland.
**params**: a window, so:
class regex
OR
`title:` and a title regex
OR
`pid:` and the pid
OR
`address:` and an address
### killactive
kills the focused window
**params**: none
### workspace
changes the workspace
params: workspace (see below)
### movetoworkspace
moves the focused window to workspace X
**params**: workspace (see below)
### movetoworkspacesilent
moves the focused window to workspace X, without changing to that workspace
(silent)
**params**: workspace (see below)
### togglefloating
toggles the focused window floating
**params**: none
### fullscreen
toggles the focused window's fullscreen state
**params**: 0 - real fullscreen (takes your entire screen), 1 - "maximize"
fullscreen (keeps the gaps and bar(s))
### dpms
sets the monitor's dpms status.
**Warning**: it is NOT recommended to set DPMS with a keybind directly, as it might cause undefined behavior. Instead, consider something like
```
bind = MOD,KEY,exec,sleep 1 && hyprctl dispatch dpms off
```
**params**: `on` for on, `off` for off.
### pseudo
toggles the focused window to be pseudotiled
**params**: none
### movefocus
moves the focus in a specified direction
**params**: l/r/u/d (left right up down)
### movewindow
moves the active window in a specified direction OR monitor
**params**: l/r/u/d (left right up down) OR mon: and ONE OF: l/r/u/d OR name OR
id (e.g.: `mon:DP-1` or `mon:l`)
### resizeactive
resizes the active window.
**params**:
- pixel delta to resize by, integer X and Y, separated by a space.
OR
- "exact" followed by a space and exact pixel size
negative X -> left, negative Y -> top, positive X -> right, positive Y -> bottom
e.g.:
```
bind=MOD,KEY,resizeactive,-20 0
bind=MOD,KEY,resizeactive,exact 1280 720
```
### moveactive
moves the active window.
**params**:
- pixel delta to move by, integer X and Y, separated by a space.
OR
- "exact" followed by a space and exact coordinates
negative X -> left, negative Y -> top, positive X -> right, positive Y -> bottom
e.g.:
```
bind=MOD,KEY,moveactive,20 -20
bind=MOD,KEY,moveactive,exact 720 0
```
### cyclenext
focuses the next window on a workspace
**params**: empty for next, `prev` for previous
### focuswindow
focuses the first found window matching a specified regex
**params**:
class regex
OR
`title:` and a title regex
OR
`pid:` and the pid
OR
`address:` and an address
### focusmonitor
focuses a monitor
**params**: direction OR name OR id
Directions: l/r/u/d (left right up down)
Name: e.g. `DP-1`
ID: e.g. `0`
(You can get names and IDs with `hyprctl monitors`)
### splitratio
changes the split ratio
**params**: relative split change, +n/-n, e.g. +0.1 or -0.02, clamps to 0.1 -
1.9
### toggleopaque
toggles the current window to always be opaque
**params**: none
### movecursortocorner
moves the cursor to the corner of the active window
**params**: direction, 0 - 3, bottom left - 0, bottom right - 1, top right - 2,
top left - 3.
### workspaceopt
toggles a workspace option for the active workspace.
**params**: a workspace option
Workspace options:
```
allfloat -> makes all new windows floating (also floats/unfloats windows on toggle)
allpseudo -> makes all new windows pseudo (also pseudos/unpseudos on toggle)
```
### exit
exits the compositor. No questions asked.
**params**: none
### forcerendererreload
forces the renderer to reload all resources and outputs.
**params**: none
### movecurrentworkspacetomonitor
Moves the active workspace to a monitor
**params**: monitor ID, name or direction (l/r/u/d)
### moveworkspacetomonitor
Moves a workspace to a monitor
**params**: workspace and monitor ID, name or direction
e.g.:
```
bind=MOD,KEY,moveworkspacetomonitor,4 0
```
will move workspace 4 to monitor 0.
### togglespecialworkspace
toggles the special workspace on/off.
**params**: none
## Workspaces
workspace args are unified. You have six choices:
ID: e.g. `1`, `2`, or `3`
Relative ID: e.g. `+1`, `-3` or `+100`
Relative workspace on monitor: e.g. `m+1`, `m-1` or `m+3`
Relative open workspace: e.g. `e+1` or `e-10`
Name: e.g. `name:Web`, `name:Anime` or `name:Better anime`
Special Workspace: `special` **Warning**: `special` is supported ONLY on
`movetoworkspace`. Any other dispatcher will result in undocumented behavior.
### Special Workspace
Special workspace is what is called a "scratchpad" in some other places. A
workspace that you can toggle on/off on any monitor.
# Executing
you can execute a shell script on startup of the compositor or on each time it's
reloaded.
**Note**: There currently is a bug with the exec that makes the executed app unable to die if killed, use `SIGKILL` (e.g. `killall name -9`) or launch from a script (`exec-once=~/myscript.sh` and do `myapp &` in the script)
`exec-once=command` will execute only on launch
`exec=command` will execute on each reload
# Curves
Defining your own Bezier curve can be done with the `bezier` keyword:
```
bezier=NAME,X0,Y0,X1,Y1
```
where `NAME` is the name, and the rest are two points for the Cubic Bezier. A
good website to design your bezier can be found
[here, on cssportal.com](https://www.cssportal.com/css-cubic-bezier-generator/).
Example curve:
```
bezier=overshot,0.05,0.9,0.1,1.1
```
# Window Rules
You can set window rules for various actions. These are applied on window open!
```
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)
you can get both by inspecting `hyprctl clients`
Examples:
```
windowrule=float,^(kitty)$
windowrule=move 0 0,title:^(Firefox)(.*)$
```
## Rules
### float
floats a window
### tile
tiles a window
### fullscreen
fullscreens a window
### move \[x\] \[y\]
moves a floating window (x,y -> int or %, e.g. 20% or 100)
### size \[x\] \[y\]
resizes a floating window (x,y -> int or %, e.g. 20% or 100)
### center
if the window is floating, will center it on the monitor.
### pseudo
pseudotiles a window
### monitor \[id\]
sets the monitor on which a window should open
### workspace \[w\]
sets the workspace on which a window should open (for workspace syntax, see
binds->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.
e.g.:
```
windowrule=workspace unset,Dolphin
windowrule=workspace name:amongus silent,kitty
windowrule=workspace 12,firefox
```
### opacity \[a\]
additional opacity multiplier
options for a:
`float` -> sets an opacity
`float float` -> sets activeopacity and inactiveopacity respectively
_Notice_: Opacity is always a PRODUCT of all opacities. E.g. active_opacity to
0.5 and windowrule opacity to 0.5 will result in a total opacity 0.25. You are
allowed to set opacities over 1, but any opacity product over 1 will cause
graphical glitches. E.g. 0.5 * 2 = 1, and it will be fine, 0.5 * 4 will cause
graphical glitches.
### opaque
forces the window to be opaque (can be toggled with the toggleopaque dispatcher)
### animation \[style\] \[opt\]
forces an animation onto a window, with a selected opt.
e.g.:
```
windowrule=animation slide left,kitty
windowrule=animation popin,dolphin
```
### rounding \[x\]
forces the application to have X pixels of rounding, ignoring the set default
(in `decoration:rounding`)
`x` has to be an int.
## More examples
```
windowrule=float,kitty
windowrule=monitor 0,Firefox
windowrule=move 200 200,Discord
```
### noblur
forces the window not to have blur
### nofocus
forces the window to never receive focus
# Animations
animations are declared with the `animation` keyword.
```
animation=NAME,ONOFF,SPEED,CURVE,STYLE
or
animation=NAME,ONOFF,SPEED,CURVE
```
for example:
```
animation=workspaces,1,8,default
animation=windows,1,10,myepiccurve,slide
```
`ONOFF` can be either 0 or 1, 0 to disable, 1 to enable.
`SPEED` is the amount of ds (1ds = 100ms) the animation will take
`CURVE` is the bezier curve name, see curves above.
`STYLE` (optional) is the animation style
The animations are a tree. If an animation is unset, it will inherit its parent's values.
_Animation tree:_
```
global
↳ windows - styles: slide, popin
↳ windowsIn - window open
↳ windowsOut - window close
↳ windowsMove - everything in between, moving, dragging, resizing.
↳ fade
↳ fadeIn - fade in (open) -> layers and windows
↳ fadeOut - fade out (close) -> layers and windows
↳ fadeSwitch - fade on changing activewindow and its opacity
↳ fadeShadow - fade on changing activewindow for shadows
↳ border
↳ workspaces - styles: slide, slidevert, fade
```
### Extras
For animation style `popin` in `windows`, you can specify a minimum percentage to start from. For example:
```
animation=windows,1,8,default,popin 80%
```
will make the animation 80% -> 100% of the size.
# Defining variables
You can define your own custom variables like this:
```
$VAR = value
```
for example:
```
$MyFavoriteGame = Among Us
```
then, to use them, simply use them. For example:
```
col.active_border=$MyColor
```
You ARE allowed to do this:
```
col.active_border=ff$MyRedValue1111
```
# Sourcing (multi-file)
Use the `source` keyword to source another file.
For example, in your `hyprland.conf` you can:
```
source=~/.config/hypr/myColors.conf
```
And Hyprland will enter that file and parse it like a Hyprland config.
Please note it's LINEAR. Meaning lines above the `source=` will be parsed first,
then lines inside `~/.config/hypr/myColors.conf`, then lines below.
# Gestures
Use something like
[libinput-gestures](https://github.com/bulletmark/libinput-gestures), with
`hyprctl` if you want to expand Hyprland's gestures beyond what's offered in
Basic Configuring.
# Submaps
If you want keybind submaps, 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:
```
bind=ALT,R,submap,resize # will switch to a submap called resize
submap=resize # will start a submap called "resize"
bind=,right,resizeactive,10 0
bind=,left,resizeactive,-10 0
bind=,up,resizeactive,0 -10
bind=,down,resizeactive,0 10
bind=,escape,submap,reset # use reset to go back to the global submap
submap=reset # will reset the submap, meaning end the current one and return to the global one.
# keybinds further down will be global again...
```
**IMPORTANT:** do not forget a keybind to reset the keymap while inside it! (In
this case, `escape`)
If you get stuck inside a keymap, you can use `hyprctl dispatch submap reset` to
go back. If you do not have a terminal open, tough luck buddy. I warned you.
# Per-device input configs
*Warning:* Some configs, notably touchpad ones, require a Hyprland restart.
Per-device config options will overwrite your options set in the `input`
section. It's worth noting that ONLY values explicitly changed will be
overwritten.
In order to apply per-device config options, make a new category like this:
```
device:name {
}
```
the `name` can be easily obtained by doing `hyprctl devices`.
Inside of it, put your config options. All options from the `input` category
(and all subcategories, e.g. `input:touchpad`) can be put inside, **EXCEPT**:
force_no_accel, follow_mouse
For example:
```
device:ROYUAN Akko Multi-modes Keyboard-B {
repeat_rate=50
repeat_delay=500
middle_button_emulation=0
}
```
*remember about the space after the end of the device's name (before the `{`)!*
# Wallpapers
The hyprland background you see when you first start Hyprland is **NOT A
WALLPAPER**, it's the default image rendered at the bottom of the render stack.
To set a wallpaper, use a wallpaper utility like
[hyprpaper](https://github.com/hyprwm/hyprpaper) or
[swaybg](https://github.com/swaywm/swaybg).
# Blurring layerSurfaces
LayerSurfaces are not windows. These are for example: Your wallpapers,
notification overlays, bars, etc.
If you really want to blur them, use `blurls=`
```
blurls=NAMESPACE
```
where `NAMESPACE` is the namespace of the layerSurface. (You can get it from
`hyprctl layers`)
to remove a namespace from being blurred (useful in dynamic situations) use:
```
blurls=remove,NAMESPACE
```

235
pages/Configuring/Basic-Config.md Normal file
View File

@ -0,0 +1,235 @@
# Basic Configuring
For basic syntax info, see
[Master Configuring](https://github.com/hyprwm/Hyprland/wiki/Configuring-Hyprland).
This page documents all the "options" of Hyprland. For binds, monitors, execs,
curves, etc. see
[Advanced Configuring](https://github.com/hyprwm/Hyprland/wiki/Advanced-config).
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
Variable types are:
`int` - integer
`bool` - boolean, `true` or `false` (`yes` or `no`, `0` or `1`) - any numerical value that is not `0` or `1` will cause undefined behaviour.
`float` - floating point number
`col` - color (e.g. 0x22334455 - alpha 0x22, red 0x33, green 0x44, blue 0x55)
`vec2` - vector with 2 values (float), separated by a space (e.g. `0 0` or
`-10.9 99.1`)
`MOD` - a string modmask (e.g. SUPER or SUPERSHIFT or
SUPERSHIFTALTCTLRCAPSMOD2MOD3MOD5 or empty for none)
Mod list:
```
SHIFT CAPS CTRL/CONTROL ALT MOD2 MOD3 SUPER/WIN/LOGO/MOD4 MOD5
```
# Sections
## General
`sensitivity=float` - mouse sensitivity (\*this is Hyprland sensitivity, added
on top of the data. To modify the data per-device, or more accurately
(sensitivities > 1 might cause mouse to jump pixels), see `input:sensitivity`)
`apply_sens_to_raw=bool` - if on, will also apply the sensitivity to raw mouse
output (e.g. sensitivity in games)
`main_mod=MOD` - the mod used to move/resize windows (hold main_mod and LMB/RMB,
try it and you'll know what I mean.)
`border_size=int` - border thickness
`no_border_on_floating=bool` - disable borders for floating windows.
`gaps_in=int` - gaps between windows
`gaps_out=int` - gaps between window-monitor edge
`col.active_border=col` - self-explanatory
`col.inactive_border=col` - self-explanatory
`cursor_inactive_timeout=int` - in seconds, after how many seconds of cursor's
inactivity to hide it. (default / never is `0`)
`damage_tracking=str` - Makes 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`.
`layout=str` - which layout to use. (Available: `dwindle`, `master`, default is
`dwindle`)
`no_cursor_warps=bool` - if true, will not warp the cursor in many cases (focusing, keybinds, etc)
## Decoration
`rounding=int` - rounded corners radius (in pixels)
`multisample_edges=bool` - enable antialiasing (no-jaggies) for rounded corners.
`no_blur_on_oversized=bool` - disable blur on oversized windows (deprecated,
leave at `0`)
`active_opacity=float` - self-explanatory, 0 - 1
`inactive_opacity=float` - self-explanatory, 0 - 1
`fullscreen_opacity=float` - self-explanatory, 0 - 1
`blur=bool` - enable dual kawase window background blur
`blur_size=int` - Minimum 1, blur size (intensity)
`blur_passes=int` - Minimim 1, more passes = more resource intensive.
Your blur "amount" is blur_size * blur_passes, but high blur_size (over around
5-ish) will produce artifacts.
If you want heavy blur, you need to up the blur_passes.
The more passes, the more you can up the blur_size without noticing artifacts.
`blur_ignore_opacity=bool` - make the blur layer ignore the opacity of the
window.
`blur_new_optimizations=bool` - whether to enable further optimizations to the blur. Recommended to turn on, as it will massively improve performance, but some people have experienced graphical issues.
`drop_shadow=bool` - enable drop shadows on windows
`shadow_range=int` - Shadow range (in pixels), more = larger shadow
`shadow_render_power=int` - (1 - 4), in what power to render the falloff (more
power, the faster the falloff)
`shadow_ignore_window=bool` - if true, the shadow will not be rendered behind
the window itself, only around it.
`col.shadow=col` - shadow's color. Alpha dictates shadow's opacity.
`col.shadow_inactive=col` - inactive shadow color. (if not set, will fall back
to col.shadow)
`shadow_offset=vec2` - shadow's rendering offset.
## Animations
`enabled=bool` - enable animations
_More about animations is on the Advanced Configuring page._
## Input
`kb_layout=str` `kb_variant=str` `kb_model=str` `kb_options=str` `kb_rules=str`
\- adequate keyboard settings
`follow_mouse=int` - (0/1/2/3) enable mouse following (focus on enter new window)
\- Quirk: will always focus on mouse enter if you're entering a floating window
from a tiled one, or vice versa. 0 - disabled, 1 - full, 2 - loose. 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.
`repeat_rate=int` - in ms, the repeat rate for held keys
`repeat_delay=int` - in ms, the repeat delay (grace period) before the spam
`natural_scroll=bool` - enable natural scroll
`numlock_by_default=bool` - lock numlock by default
`force_no_accel=bool` - force no mouse acceleration, bypasses most of your
pointer settings to get as raw of a signal as possible.
`sensitivity=float` - set the libinput sensitivity. This **HAS** to be from -1
to 1, or else it will be clamped.
### Touchpad
_Subcategory input:touchpad:_
`disable_while_typing=bool` - self-explanatory
`natural_scroll=bool` - self-explanatory
`clickfinger_behavior=bool` - self-explanatory
`middle_button_emulation=bool` - self-explanatory
`tap-to-click=bool` - self-explanatory
*Note:* Touchpad config changes may require a Hyprland restart.
### Per-device input config is described [here](https://github.com/hyprwm/Hyprland/wiki/Advanced-config#per-device-input-configs)
## Gestures
`workspace_swipe=bool` - enable workspace swipe gesture
`workspace_swipe_fingers=int` - how many fingers for the gesture
`workspace_swipe_distance=int` - in px, the distance of the gesture
`workspace_swipe_invert=bool` - invert the direction
`workspace_swipe_min_speed_to_force=int` - minimum speed in px per timepoint to
force the change ignoring `cancel_ratio` (default `30`) Setting to `0` will
disable this mechanic.
`workspace_swipe_cancel_ratio=float` - (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)
## Misc
`disable_hyprland_logo=bool` - disables the hyprland logo background.
`disable_splash_rendering=bool` - disables the hyprland splash rendering.
(requires a monitor reload to take effect)
`no_vfr=bool` - disables VFR (variable frame rate) - VFR increases battery life
at the expense of possible issues on a few monitors. (VFR is off by default)
`damage_entire_on_snapshot=bool` - Damage the entire monitor when rendering snapshots. Recommended with transformed displays. Do not use without transformed displays.
`mouse_move_enables_dpms=bool` - If DPMS is set to off, wake up the monitors if the mouse moves.
`always_follow_on_dnd=bool` - By default enabled, 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.
`layers_hog_keyboard_focus=bool` - If true, will make keyboard interactive layers keep their focus on mouse move (e.g. wofi, bemenu)
## Binds
`pass_mouse_when_bound=bool` - if disabled, will not pass the mouse events to
apps / dragging windows around if a keybind has been triggered. (Enabled by
default)
`scroll_event_delay=int` - in ms, how many ms to wait after a scroll event to
allow to pass another one for the binds.
## Debug
### only for developers
`overlay=bool` - print the debug performance overlay.
`damage_blink=bool` - (epilepsy warning!) flash areas updated with damage
tracking
`disable_logs=bool` - disables the logs
`disable_time=bool` - disables time logging, by default it's `true`
## More
There are more config options described in other pages, which are layout- or
circumstance-specific. See the sidebar navpanel for more pages.

53
pages/Configuring/Configuring-Hyprland.md Normal file
View File

@ -0,0 +1,53 @@
# Configuring
The config is located in `~/.config/hypr/hyprland.conf`.
I recommend you copy the `examples/hyprland.conf`, but you can also edit the
autogenerated config.
By removing the line `autogenerated=1` you'll remove the yellow warning.
The Hyprland config is very similiar in syntax to the Hypr config. The only
difference is that all the variables that didn't have a section are now in the
section `general`.
There is no "reload" keybind. The config is reloaded the moment you save it.
Refer to the example config in `/examples/hyprland.conf` to see, well... an
example.
Start a section with `name {` and end in `}` ***in separate lines!***
# Line style
every config line is a command followed by a value.
```
COMMAND=VALUE
```
The command can be a variable, or a special keyword (described further in this
page)
You are **allowed to** input trailing spaces at the beginning and end.
e.g.:
```
COMMAND = VALUE
```
is valid.
# Basic configuring
To configure the "options" of Hyprland, animations, styling, etc. see
[Basic Configuring](https://github.com/hyprwm/Hyprland/wiki/Basic-Config).
# Advanced configuring
Some keywords (binds, curves, execs, monitors, etc.) arent variables but define
special behaviour.
See all of them in
[Advanced Configuring](https://github.com/hyprwm/Hyprland/wiki/Advanced-config)

76
pages/Configuring/Dwindle-Layout.md Normal file
View File

@ -0,0 +1,76 @@
# Dwindle Layout
Dwindle is a BSPWM-like layout, where every window on a workspace is a member of
a binary tree.
# Quirks
Dwindle splits are NOT PERMANENT. The split is determined dynamically with the
W/H ratio of the parent node. If W > H, it's side-by-side. If H > W, it's
top-and-bottom. You can make them permanent by enabling `preserve_split`.
Dwindle allows for mouse moving and resizing using the `main_mod` and the mouse
(left for move, right for resize)
_Moving (main_mod + LMB)_
![moveExampleHyprland](https://user-images.githubusercontent.com/43317083/162996595-c2b41ab1-0f3b-4680-99df-34d6dbad87f4.gif)
_Resizing (main_mod + RMB)_
![resizeExampleHyprland](https://user-images.githubusercontent.com/43317083/162996612-6341199a-eeee-4de0-85ee-f6a42c426c3f.gif)
## Grouped (tabbed) windows
Dwindle allows you to make a group with the `togglegroup` bind dispatcher, and
cycle through it with `changegroupactive`.
A group is like i3wm's "tabbed" container. It takes the space of one window, and
you can change the window to the next one in the tabbed "group".
When creating the group, a group will be made from the current active window,
and all children (recursively!) of the parent node. The new group's border
colors are configurable with the appropriate `col.` settings in the config
section below.
_Grouping example (make, add, toggle, remove)_
![groupExampleSmaller](https://user-images.githubusercontent.com/43317083/163003581-69d7a5d0-5757-4183-83f1-256cdc99c96a.gif)
Closing windows within the groups is allowed, however, since the groups in the
backend are still a tree, if you remove a node that makes the original node
container get removed, the group will be broken back to its dwindle form.
# Config
category name: `dwindle`
`pseudotile=int` - (0/1) enable pseudotiling
`col.group_border=col` - inactive (out of focus) group border color
`col.group_border_active=col` - active group border color
`force_split=int` - 0 -> split follows mouse, 1 -> always split to the left (new
= left or top) 2 -> always split to the right (new = right or bottom)
`preserve_split=int` - (0/1) if enabled, the split (side/top) will not change
regardless of what happens to the container.
`special_scale_factor=float` - 0 - 1 -> specifies the scale factor of windows on
the special workspace
`split_width_multiplier=float` - specifies the auto-split width multiplier
`no_gaps_when_only=bool` - whether to apply gaps when there is only one window on a workspace.
## Bind Dispatchers
`togglegroup` - toggles the current window and its siblings (recursively) into a
group - params: none
`changegroupactive` - switches to the next window in a group. - params: b -
back, f - forward.
`togglesplit` - toggles the split (top/side) of the current window - params:
none

27
pages/Configuring/Expanding-functionality.md Normal file
View File

@ -0,0 +1,27 @@
# Expanding functionality
Hyprland exposes two powerful sockets for you to use.
The first, socket1, can be fully controlled with `hyprctl`, see its usage [here](https://github.com/hyprwm/Hyprland/wiki/Using-hyprctl).
The second, socket2, sends events for certain changes / actions and can be used to react to different events. See its description [here](https://github.com/hyprwm/Hyprland/wiki/IPC).
## Example script
This bash script will change the outer gaps to 20 if the currently focused monitor is DP-1, and 30 otherwise.
```bash
#!/bin/sh
function handle {
if [[ ${1:0:10} == "focusedmon" ]]; then
if [[ ${1:12:4} == "DP-1" ]]; then
hyprctl keyword general:gaps_out 20
else
hyprctl keyword general:gaps_out 30
fi
fi
}
socat - UNIX-CONNECT:/tmp/hypr/$(echo $HYPRLAND_INSTANCE_SIGNATURE)/.socket2.sock | while read line; do handle $line; done
```

46
pages/Configuring/Master-Layout.md Normal file
View File

@ -0,0 +1,46 @@
# Master layout
The master layout makes one window be the "master", taking the left part of the
screen, and tiles the rest on the right.
# Quirks
The right, "slave" windows will always be split uniformly. You cannot change
their size.
![master1](https://user-images.githubusercontent.com/43317083/179357849-321f042c-f536-44b3-9e6f-371df5321836.gif)
You can, however, resize the master window.
![master2](https://user-images.githubusercontent.com/43317083/179357863-928b0b5a-ff10-4edc-aa76-3ff88c59c980.gif)
# Config
*category name `master`*
`special_scale_factor=float` - (0.0 - 1.0) the scale of the special workspace
windows
`new_is_master=bool` - whether a newly open window should replace the master or
join the slaves.
`new_on_top=bool` - whether a newly open window should be on the top of the
stack
`no_gaps_when_only=bool` - whether to apply gaps when there is only one window on a workspace.
## Dispatchers
`layoutmsg` params:
`swapwithmaster` -> swaps the current window with master
`cyclenext` -> focuses the next window respecting the layout
`cycleprev` -> focuses the previous window respecting the layout
example usage:
```
bind=MOD,KEY,layoutmsg,cyclenext
```

33
pages/Configuring/Uncommon-tips-&-tricks.md Normal file
View File

@ -0,0 +1,33 @@
# Uncommon tips & tricks
## Switchable keyboard layouts
An example of a switchable keyboard layout between US and RU, where you switch
between them with SUPER+A (SUPER+Ф)
```
bind=SUPER,A,exec,hyprctl keyword input:kb_layout ru
bind=SUPER,Cyrillic_ef,exec,hyprctl keyword input:kb_layout us
```
You can apply this to any number of languages, mix'n'match, etc.
Please note that if a keyboard layout has a different alphabet, mappings for "a"
"b" "c" will be replaced with mappings from that language. (meaning, e.g.
`SUPER+D` will not work on a `ru` layout, because the russian layout does not
have a `D`.)
If you are unsure about the key names of your chosen alphabet, refer to the
[xkbcommon keysym header](https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h).
The keysym name in Hyprland is the XKB define name without the `XKB_KEY_`.
## Disabling keybinds with one master keybind
If you want to disable all keybinds with another keybind (make a kaybind toggle of sorts) you can just use a submap with only a keybind to exit it.
```
bind=MOD,KEY,submap,clean
submap=clean
bind=MOD,KEY,submap,reset
submap=reset
```

107
pages/Configuring/Using-hyprctl.md Normal file
View File

@ -0,0 +1,107 @@
# 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`.
# Commands
## Control
### 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.
Examples:
```
hyprctl dispatch exec kitty
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
```
Returns: `ok` on success, an error message on fail.
### Reload
issue a `reload` to force reload the config.
### kill
issue a `kill` to get into a kill mode, where you can kill an app by clicking on
it. You can exit it with ESCAPE.
Kind of like xkill.
### setcursor
Sets the cursor theme and reloads the cursor manager. Will set the theme for everything except GTK, because GTK.
params: theme and size
e.g.:
```
hyprctl setcursor Bibata-Modern-Classic 24
```
## Info
```
version - prints the hyprland version, meaning flags, commit and branch of build.
monitors - lists all the outputs with their properties
workspaces - lists all workspaces with their properties
clients - lists all windows with their properties
devices - lists all connected keyboards and mice
activewindow - gets the active window name
layers - lists all the layers
splash - prints the current random splash
getoption [option] - gets the config option status (values)
```
# 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
# Flags
You can specify flags for the request like this:
```
hyprctl -j monitors
```
flag list:
```
j -> output in JSON
```

84
pages/Contributing and Debugging/_index.md Normal file
View File

@ -0,0 +1,84 @@
# Contributing guidelines
For PRs, make sure that you:
- follow the code style
- don't write "hacky" code
- check and test the code
- are contributing something useful
- explain your PR as best as you can
For issues, please see
[the guidelines](https://github.com/hyprwm/Hyprland/blob/main/docs/ISSUE_GUIDELINES.md)
# Build in debug
## Required packages
`xcb` stuff, check with your local package provider.
`wlroots-git` - always have the latest wlroots.
`wayland` - of course.
*Arch*:
`yay -S gdb ninja gcc cmake libxcb xcb-proto xcb-util xcb-util-keysyms libxfixes libx11 libxcomposite xorg-xinput libxrender pixman wayland-protocols cairo pango`
(If any are missing hmu)
## Recommended, CMake
install the VSCode C/C++ and CMake Tools extensions and use that.
I've attached a launch.json to examples/ that you can copy to your .vscode/
folder in the repo root.
With that, you can build in debug, go to the debugging tab and hit
`(gdb) Launch`.
## Custom, CLI
`make debug`
attach and profile in your preferred way.
## Notice
For all ways, make sure to `sudo make clear` to clear any root-owned files.
Also, before the first build (or after some updates, possibly)
`sudo make config`. (If you get any `missing header file "...-protocol.h"`, you
need to `make config`.)
# Running
when running Hyprland in Debug mode, the config is
`~/.config/hypr/hyprlandd.conf` and the logs can be found at
`/tmp/hypr/[INSTANCE SIGNATURE]/hyprlandd.conf`.
# Logs, dumps, etc.
You can use the logs and the GDB debugger, but running Hyprland in debug compile
as a driver and using it for a while might give more insight to the more random
bugs.
When Hyprland crashes, use `coredumpctl` and then `coredumpctl info PID` to see
the dump.
I also recommend the amazing command
`watch -n 0.1 "cat /tmp/hypr/$(echo HYPRLAND_INSTANCE_SIGNATURE)/hyprland.log | grep -v \"arranged\" | tail -n 40"`
for live logs. (replace `hyprland` with `hyprlandd` for debug builds)
# Nesting Hyprland
Hyprland can run nested in a window. For that, make sure you did the following:
- built in debug
- removed ALL `exec=` and `exec-once=` keywords from your debug config (`hyprlandd.conf`)
- set a resolution and are not using `preferred`
- made sure no keybinds overlap (I recommend using a different mod for your keybinds altogether)
Once you launch, the display will probably be completely garbled. To fix that, in the parent, do a `hyprctl clients` and note the size of the window. Make sure while opening the terminal to not resize the nested window. Note that resolution and use it down to the pixel in your `hyprlandd.conf`.
If you segfault in `shadowKeybinds`, you probably either are using the same mod as your parent or resized the window.

44
pages/Crashes and Bugs/_index.md Normal file
View File

@ -0,0 +1,44 @@
## Getting the log
If you are in a TTY, and the hyprland session that crashed was the last one you
launched, the log will be printed with
```
cat /tmp/hypr/$(ls -t /tmp/hypr/ | head -n 1)/hyprland.log
```
feel free to send it to a file, save, copy, etc.
if you are in a Hyprland session, and you want the log of the last session, use
```
cat /tmp/hypr/$(ls -t /tmp/hypr/ | head -n 2 | tail -n 1)/hyprland.log
```
## Crashes at launch
Diagnose the issue by what is in the log:
- `sWLRBackend was NULL!` -> launch in the TTY and refer to the wlr logs in RED.
- `Monitor X has NO PREFERRED MODE, and an INVALID one was requested` -> your
monitor is bork.
- Other -> see the coredump. Use `coredumpctl`, find the latest one's PID and do
`coredumpctl info PID`.
- failing on a driver (e.g. `radeon`) -> try compiling with
`make legacyrenderer`, if that doesn't help, report an issue.
- failing on `wlr-xxx` -> try compiling with `make legacyrenderer`, if that
doesn't help, report an issue, and also refer to the TTY wlr logs in RED like
in the first point.
- failing on `Hyprland` -> report an issue.
## Crashes not at launch
Report an issue on Github or on the Discord server.
## Bugs
First of all, ***READ THE
[FAQ PAGE](https://github.com/hyprwm/Hyprland/wiki/FAQ)***
If your bug is not listed there, you can ask on the Discord server or open an
issue on Github.

272
pages/FAQ/_index.md Normal file
View File

@ -0,0 +1,272 @@
### Nothing renders / screen is empty / crash on opening first app
Possible causes:
#### Your themes are not set up properly, making apps crash.
Use something like `qt5ct` (QT) and `lxappearance` (GTK) (\*for GTK you can also
set up themes with envvars) to set up your themes.
#### Your PC is very, very old.
In that case, see the
[Installation Page](https://github.com/hyprwm/Hyprland/wiki/Installation) and
try compiling with LEGACY_RENDERER
*For more info about bugs and crashes, see this*
*[wiki page](https://github.com/hyprwm/Hyprland/wiki/Crashing-and-bugs)*
### Me cursor no render?
Are you on NVIDIA? If so, then you have been a naughty boy and haven't listened
to my tips on other pages. Use the `WLR_NO_HARDWARE_CURSORS=1` envvar.
### How do I screenshot?
Install `grim-git` and `slurp`
Use a keybind (or execute) `grim -g $(slurp)`, select a region. A screenshot
will pop into your `~/Pictures/` (You can configure grim and slurp, see their
github pages)
### How do I change my wallpaper?
Install hyprpaper, swaybg or any other wlroots-compatible wallpaper utility.
### My workspace (2, 3, or any other) is like... bugged?
You did the below, unknowingly.
### How do I mirror a screen?
Mirroring isn't *officially* supported, it's technically a bug, but it works.
Make sure the screen you want mirrored is the same resolution as the source.
Then, just make them overlap in the layout, e.g. making the primary monitor at
0x0 and the mirrored one on 0x0 as well.
That creates an issue though, as the mirrored output also *has* to have an
active workspace, and usually will be annoyingly taking 2,3 etc, while making
them unreachable. An easy fix is to assign e.g.
`workspace=MIRROREDSCREEN,name:unused` and never use it.
### How heavy is this?
Not that much heavier than Xorg. If you want maximum performance, consider
turning off the blur and animations.
### Blur makes my GPU cry :(
You probably forgot to turn on `decoration:blur_new_optimizations`. Thank me later.
### My monitor no worky!
Try changing the mode in your config. If your preferred one doesn't work, try a
lower one. A good way to list all modes is to get `wlr-randr` and do a
`wlr-randr --dryrun`
### How do I get a coredump?
*These instructions are ONLY for systemd. If you use anything else, you should
know what you're doing.*
Launch `coredumpctl` in a terminal. Press "END" on the keyboard to go to the
end. Note the **last** (the one furthest to the bottom) crash that has
`/usr/bin/Hyprland` as an executable. Remember the PID of it (the first number
after the date in a given line) exit (Ctrl+C) type `coredumpctl info PID` where
PID is the remembered PID. Send the entire thing.
### How do I update?
open a terminal where you cloned the repo.
`git pull && sudo make clear && sudo make install`
### Screenshare / OBS no worky!
Yes, hello, this is Wayland.
Amazing gist just about that:
https://gist.github.com/PowerBall253/2dea6ddf6974ba4e5d26c3139ffb7580
Please remember in OBS you need to select "Pipewire screen capture" as the
source.
### Howdy I screen lock???
Use a wayland-compatible locking utility using WLR protocols, e.g. `swaylock`.
### How do I change me mouse cursor?
Use a tool like for example `lxappearance` to change the GTK cursor.
After that, add `exec-once=hyprctl setcursor [THEME] [SIZE]` to your config and restart Hyprland.
If that doesn't work, change the config files manually according to
the
[XDG specification (Arch wiki link)](https://wiki.archlinux.org/title/Cursor_themes#Configuration).
Make sure to also edit `~/.config/gtk-4.0/settings.ini` and `~/.gtkrc-2.0` if
_not_ using a tool (like `lxappearance`).
Then, do a `gsettings set $gnome-schema cursor-theme 'theme-name'` and you're
all good!
If it still doesn't work
### GTK Settings no work / whatever!
[https://github.com/swaywm/sway/wiki/GTK-3-settings-on-Wayland](https://github.com/swaywm/sway/wiki/GTK-3-settings-on-Wayland)
### My \[program name\] is freezing!
Make sure you have a notification daemon running, for example `dunst`. Autostart
it with the `exec-once` keyword.
### I want to use Waybar, but the workspaces don't work!
Copy the Waybar source, edit `include/factory.hpp` and add
```
#define HAVE_WLR
#define USE_EXPERIMENTAL
```
on top. If you want to also have sway modules (or any other defined in the file)
add the appropriate defines.
All `#ifdef HAVE_<thing>` can be enabled by adding `#define HAVE_<thing>` on
top.
Then compile according to the instructions on the Waybar github repo.
Use the `wlr/workspaces` module.
Please do not blame me for this, it's the Waybar dev that doesn't include
experimental in the base binary for whatever reason.
### Waybar doesn't show the active workspace!
Use the style for `#workspaces button.active`
### How do I autostart my favorite apps?
Using the window rules to assign apps to workspace you can setup a session start
script to open a bunch of applications on various workspaces. The following
method will start these apps silently (i.e. without the flickering from
workspace to workspace) and deassign the rule so that subsequent start of this
app will not start it on the initially assigned workspace (which could be a drag
if e.g. you want kitty to be started on ws 1 while you need kitty to open on any
workspace subsequently).
Put the following in your hyprdland.conf: (example)
```
windowrule=workspace 1 silent,kitty
windowrule=workspace 1 silent,Subl
windowrule=workspace 3 silent,Mailspring
windowrule=workspace 4 silent,firefox
[...]
exec-once=kitty
exec-once=subl
exec-once=mailspring
exec-once=firefox
[...]
exec-once=cleanup_after_start.sh
```
where `cleanup_after_start.sh` script contains:
```
sleep 10
hyprctl keyword windowrule "workspace unset,kitty"
hyprctl keyword windowrule "workspace unset,Subl"
hyprctl keyword windowrule "workspace unset,Mailspring"
hyprctl keyword windowrule "workspace unset,firefox"
```
in `sleep 10`, the 10 is of course only a suggestion.
### Howdy I move my favorite workspaces to a new monitor when I plug it in?
if you want workspaces to automatically go to a monitor upon connection, use the
following:
In hyprland.conf:
```
exec-once=handle_monitor_connect.sh
```
where `handle_monitor_connect.sh` is: (example)
```
#!/bin/sh
function handle {
if [[ ${1:0:12} == "monitoradded" ]]; then
hyprctl dispatch moveworkspacetomonitor "1 1"
hyprctl dispatch moveworkspacetomonitor "2 1"
hyprctl dispatch moveworkspacetomonitor "4 1"
hyprctl dispatch moveworkspacetomonitor "5 1"
fi
}
socat - UNIX-CONNECT:/tmp/hypr/.socket2.sock | while read line; do handle $line; done
```
if you want workspaces 1 2 4 5 to go to monitor 1 when connecting it.
Please note this requires `socat` to be installed.
### My tablet no worky??
Use [Open Tablet Driver](https://github.com/OpenTabletDriver/OpenTabletDriver)
to configure your tablet. In the future it will be supported in the config.
Until then, OTD.
### Some of my apps take a really long time to open...?
*~/.config/hypr/hyprland.conf*
```
exec-once=systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
```
### My cursor in QT apps is too big!
The QT cursor size can be fixed by setting the envvar `XCURSOR_SIZE=24`. You
should probably add it to your exported envvars.
### How do I export envvars for Hyprland?
As with any Display Server, Xorg included, you should probably make a script to
launch it, for example:
```
export AMONG_US=1
exec Hyprland
```
and launch that. (For Login Manager users, you can replace the "exec" entry in
the .desktop file to point to your script)
### I get random white flashes!
Try disabling VFR with `misc:no_vfr=1`
### How do I make Hyprland draw as little power as possible on my laptop?
I assume you already have `damage_tracking` on full. If you don't, do it. It's heavily advised to use `full` regardless of anything.
Optimization options:
*feel free to ignore any that you find causing issues*
`decoration:blur_new_optimizations = true`
`decoration:blur = false`
`decoration:drop_shadow = false`
`misc:no_vfr = false`

198
pages/Getting Started/Installation.md Normal file
View File

@ -0,0 +1,198 @@
# Foreword
Nvidia GPUs are widely known as... yeah. If you want to try Hyprland on Nvidia regardless (many people have reported successes), follow the [Nvidia page](https://github.com/hyprwm/Hyprland/wiki/Nvidia) after installing Hyprland.
### Distros
Arch and NixOS are very supported. For any other distro (not based on Arch/Nix)
you might have varying amounts of success. However, since Hyprland is extremely
bleeding-edge, distros like Pop!\_OS, Ubuntu, etc. etc. might have **major**
issues running Hyprland.
# Installation
Installing Hyprland is very easy. Either you install it from your local package
provider (if they provide pkgs for Hyprland) or you install/build it yourself.
**Notice:** Given this project is under development and constantly changing, if
you want to keep up to date with the latest commits, please consider updating
your packages with `yay -Syu --devel`, or your other preferred package manager.
## Packages
**WARNING:** I do not maintain any packages. If they are broken, try building
from source first.
## Arch Linux
*AUR:*
```
hyprland-git - compiles from latest source
hyprland - compiles from latest release source
hyprland-bin - compiled latest release
```
*If you're on Arch Linux, I* ***heavily*** *recommend you use the AUR.*
## Nix
Read the [Nix page](https://github.com/hyprwm/Hyprland/wiki/Nix).
## Fedora
[https://github.com/hyprwm/Hyprland/discussions/284](https://github.com/hyprwm/Hyprland/discussions/284)
## Manual (Releases)
Download the most recent release.
copy the binary (Hyprland) to `/usr/bin/`.
copy hyprctl to `/usr/bin/`.
copy the wlroots .so (`wlroots.so.XX032`) to `/usr/lib/`.
copy the desktop entry (`examples/Hyprland.desktop`) to
`/usr/share/wayland-sessions/`
the example config is in `examples/Hyprland.conf`.
For updating later on, you can overwrite the binaries (hyprctl, hyprland and
libwlroots), you don't need to update anything else.
## Manual (Manual Build)
*Arch dependencies*:
`yay -S gdb ninja gcc cmake libxcb xcb-proto xcb-util xcb-util-keysyms libxfixes libx11 libxcomposite xorg-xinput libxrender pixman wayland-protocols cairo pango`
(If any are missing hmu)
Please note Hyprland builds `wlroots`. Make sure you have the dependencies of
wlroots installed, you can make sure you have them by installing wlroots
separately (Hyprland doesn't mind)
Also note that Hyprland uses the C++23 standard, so your compiler has to support
that (`gcc>=12.1.0` or `clang>=15`)
### CMake (recommended)
then...
```
git clone --recursive https://github.com/hyprwm/Hyprland
cd Hyprland
sudo make install
```
### Meson
then...
```
meson _build
ninja -C _build
ninja -C _build install
```
Refer to Debugging to see how to build & debug.
## Crashes at launch
See the log, `cat /tmp/hypr/[INSTANCE_SIGNATURE]/hyprland.log`
*If you are unsure of the signature, grab the one thats the most recently
modified.*
Diagnose the issue by what is in the log:
- `sWLRBackend was NULL!` -> launch in the TTY and refer to the wlr logs in RED.
- `Monitor X has NO PREFERRED MODE, and an INVALID one was requested` -> your
monitor is bork.
- Other -> see the coredump. Use `coredumpctl`, find the latest one's PID and do
`coredumpctl info PID`.
- failing on a driver (e.g. `radeon`) -> try compiling with
`make legacyrenderer`, if that doesn't help, report an issue.
- failing on `wlr-xxx` -> try compiling with `make legacyrenderer`, if that
doesn't help, report an issue, and also refer to the TTY wlr logs in RED like
in the first point.
- failing on `Hyprland` -> report an issue.
## Custom installation (legacy renderer, etc)
cd into the hyprland repo.
for legacy renderer:
```
sudo make clear && sudo make config && make legacyrenderer && sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions
```
_please note the legacy renderer may not support some graphical features._
<br/><br/> Any other config: (replace \[PRESET\] with your preset, `release`
`debug` `legacyrenderer` `legacyrendererdebug`)
```
sudo make clear && sudo make config && make [PRESET] && sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions
```
## Custom Build flags
To apply custom build flags, you'll have to ditch make.
Supported custom build flags:
```
NO_XWAYLAND - Removes XWayland support
```
How to?
Go to the root repo.
Clean before everything and config the root:
```
make clear && sudo make config
```
Then, configure CMake:
```
mkdir -p build && cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -D<YOUR_FLAG>:STRING=true -H./ -B./build -G Ninja
```
Change `<YOUR_FLAG>` to one of the custom build flags. You **are allowed to**
use multiple at once, then add another `-D<YOUR_FLAG_2>:STRING=true`
You can of course also change the `BUILD_TYPE` to `Debug`.
Now, build:
```
cmake --build ./build --config Release --target all -j 10
```
If you configured in `Debug`, change the `--config` to `Debug` as well.
Now, of course, install manually.
```
sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions
```
# Launching
You can launch Hyprland by either going into a TTY and executing `Hyprland`, or
with a login manager.
**!IMPORTANT**: Do **not** launch Hyprland with `root` permissions (don't
`sudo`)
Login managers are not officially supported, but here's a short compatibility
list:
- SDDM → Works flawlessly
- GDM → Works with the caveat of crashing Hyprland on the first launch
- ly → Works with minor to major issues and/or caveats

105
pages/Getting Started/Quick-start.md Normal file
View File

@ -0,0 +1,105 @@
# Quick start
After you've installed Hyprland, you can either launch it from a TTY with
`Hyprland` or from a login manager. Although login managers aren't officially
supported, I recommend `SDDM`, as it's been working flawlessly with wayland
compositors.
It is recommended you have `kitty` for terminal access, (example and autogenerated configs have it bound to SUPER+Q) or for you to manually change it in the config before launching hyprland.
If you have an Nvidia card, please also take a look at [The nvidia page](https://github.com/hyprwm/Hyprland/wiki/Nvidia) before launching. You should **first** make a wrapper, as described in the section below, then follow the instructions from the Nvidia page, and then continue on with sections below.
## Wrapping the launcher (recommended)
With Xorg, you get the `.xinitrc`. With Hyprland, you can create your own... kind of.
Make an executable file somewhere in your `PATH`, for example `~/.local/bin/`, called (for example) `wrappedHl`
In it, put:
```
#!/bin/bash
cd ~
export _JAVA_AWT_WM_NONREPARENTING=1
export XCURSOR_SIZE=24
exec Hyprland
```
you can add as many exported envvars as you need (nvidia users might need a lot), but I recommend to have *at least* the shown two. You can also change the shell you launch this with, although it shouldn't matter.
You should now launch Hyprland with `wrappedHl` instead of `Hyprland`. Make sure to edit your .desktop file in `/usr/share/wayland-sessions/` if you use a login manager! (You might need to put the full path in it, as login managers are usually not ran through the user account)
## Immediate
**OMG MY SCREEN IS BROKEN, FLASHY TEARY!** -> see the bottom of this page
Once you log in, you'll be greeted with a yellow warning that will give you some
basic keybind info of your pregenerated config.
I recommend you use the config provided in `examples/hyprland.conf` though.
Paste it into `~/.config/hypr/hyprland.conf`
You can, of course, start from the pregenerated config if you wish to. If you
want the warning to go away, remove the `autogenerated=1` line.
## Monitors
Use `hyprctl monitors` to list available outputs.
Then, you can configure your outputs with
```
hyprctl keyword monitor NAME,RES@HZ,OFFSET,SCALE
```
`NAME` is the name of the display, e.g. `DP-1`, can be empty for a global rule.
`RES@HZ` is the resolution and refresh rate, e.g. `1920x1080@144`
`OFFSET` is the position of the monitor, e.g. `0x0`
`SCALE` is the display scale, e.g. `1`
example command:
```
hyprctl keyword monitor DP-3,1920x1080@240,1920x0,1
```
**Warning!** These changes are **not** permanent! If you want to make those
changes persist, configure your outputs in the config!
# Proper configuring
Head onto the
[Master Configuring Wiki Page](https://github.com/hyprwm/Hyprland/wiki/Configuring-Hyprland)
to learn all about configuring Hyprland to your likings.
# Apps / X11 replacements
See the [Useful Utilities Page](https://github.com/hyprwm/Hyprland/wiki/Useful-utilities) and the
[Sway wiki page](https://github.com/swaywm/sway/wiki/Useful-add-ons-for-sway)
just about that.
# Screen broken on launch
This usually happens due to your monitor not being very happy about the default
settings.
You can get your monitor's name(s) from the TTY.
Exit hyprland, and then:
- `cat /tmp/hypr/$(ls -t /tmp/hypr | head -n 1)/hyprland.log | grep monitor`
will give you a bunch of logs about the connected monitors. Names like `DP-x`
or `HDMI-x` etc are your monitor names.
- edit (with your favorite text editor) `~/.config/hypr/hyprland.conf`
- replace the `monitor=` line with `monitor=NAME,RES@Hz,OFFSET,SCALE`, for
example `monitor=DP-1,1920x1080@60,0x0,1` (See the above section titled
Monitors for more info about the values) You can also add multiple of those
for multi-mon setups.
After this, upon launching Hyprland again, provided you set an appropriate mode
for your monitors, everything should be fine.

12
pages/Home.md Normal file
View File

@ -0,0 +1,12 @@
# Hyprland Wiki
Hello there, dear traveler! Welcome to the Hyprland Wiki!
Take a tour of the pages on the right and read ones that you may need.
## IMPORTANT
if you are having issues, please try reading the FAQ section and both
configuring sections. Chances are your issue is described somewhere there. If
not, you can try searching the issues or joining the discord server (link in the
README, click the join discord server button)

92
pages/IPC/_index.md Normal file
View File

@ -0,0 +1,92 @@
# IPC
Hyprland exposes 2 UNIX Sockets, for controlling / getting info about Hyprland
via code / bash utilities.
## Hyprland Instance Signature (HIS)
```
echo $HYPRLAND_INSTANCE_SIGNATURE
```
# /tmp/hypr/\[HIS\]/.socket.sock
Used for hyprctl-like requests. See the
[Hyprctl page](https://github.com/hyprwm/Hyprland/wiki/Using-hyprctl) for
commands.
basically, write `command args`.
# /tmp/hypr/\[HIS\]/.socket2.sock
Used for events. Hyprland will write to each connected client live events like
this:
`EVENT>>DATA\n` (\\n is a linebreak)
e.g.: `workspace>>2`
## Events list:
### workspace
emitted on workspace change. Is emitted ONLY when a user requests a workspace
change, and is not emitted on mouse movements (see `activemon`)
Data: WORKSPACENAME
### focusedmon
emitted on the active monitor being changed.
Data: MONNAME,WORKSPACENAME
### activewindow
emitted on the active window being changed.
Data: WINDOWCLASS,WINDOWTITLE
### fullscreen
emitted when a fullscreen status of a window changes.
Warning: a fullscreen event is not guaranteed to fire on/off once in succession.
A window might do for example 3 requests to be fullscreen'd, which would result
in 3 fullscreen events.
Data: 0/1 (exit fullscreen / enter fullscreen)
### monitorremoved
emitted when a monitor is removed (disconnected)
Data: MONITORNAME
### monitoradded
emitted when a monitor is added (connected)
Data: MONITORNAME
### createworkspace and destroyworkspace
emitted when a workspace is created or removed
Data: WORKSPANCENAME
## How to use socket2 with bash
example script using socket2 events with bash and `socat`:
```
#!/bin/sh
function handle {
if [[ ${1:0:12} == "monitoradded" ]]; then
# do_something
fi
}
socat - UNIX-CONNECT:/tmp/hypr/$(echo $HYPRLAND_INSTANCE_SIGNATURE)/.socket2.sock | while read line; do handle $line; done
```

110
pages/Nix/_index.md Normal file
View File

@ -0,0 +1,110 @@
# Nix
**NOTE:** Hyprland is NOT supported on NixOS stable. It may (not) compile or
work as intended. Please use the flake.
## Install and configure Hyprland on Nix & NixOS
Make sure to check out the options of the
[Nix module](https://github.com/hyprwm/Hyprland/blob/main/nix/module.nix).
### With flakes
```nix
# flake.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
hyprland = {
url = "github:hyprwm/Hyprland";
# build with your own instance of nixpkgs
inputs.nixpkgs.follows = "nixpkgs";
};
};
outputs = { self, nixpkgs, hyprland }: {
nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
# ...
modules = [
hyprland.nixosModules.default
{ programs.hyprland.enable = true; }
# ...
];
};
};
```
Don't forget to replace `HOSTNAME` with your hostname!
### Without flakes
**NOTE:** If you're using Hyprland through an overlay, set
`programs.hyprland.package = pkgs.hyprland;`.
```nix
# configuration.nix
{config, pkgs, ...}: let
flake-compat = builtins.fetchTarball "https://github.com/edolstra/flake-compat/archive/master.tar.gz";
hyprland = (import flake-compat {
src = builtins.fetchTarball "https://github.com/hyprwm/Hyprland/archive/master.tar.gz";
}).defaultNix;
in {
imports = [
hyprland.nixosModules.default
];
nixpkgs.overlays = [ hyprland.overlays.default ];
programs.hyprland = {
enable = true;
package = pkgs.hyprland;
};
}
```
## Home Manager module
You can use the Home Manager module by adding it to your configuration:
```nix
{ config, pkgs, inputs, ... }: {
imports = [
inputs.hyprland.homeManagerModules.default
];
wayland.windowManager.hyprland.enable = true;
# ...
}
```
For a list of available options, check the
[module file](https://github.com/hyprwm/Hyprland/blob/main/nix/hm-module.nix).
## Modules mix'n'match
If you plan on using the HM module alongside the NixOS module, set the NixOS
`programs.hyprland.package = null;`.
If you don't plan on using the NixOS module, but want to use the HM module, you
will have to enable all the options the NixOS module enables.
If you don't plan on using any module, manually enable whatever options the
modules set.
## Cachix
A [Hyprland Cachix](https://app.cachix.org/cache/nix-gaming) exists to cache
the `wlroots` package and speed up builds.
In case you don't plan on changing the Nixpkgs Hyprland builds with, you can
use this cache to speed up your builds.
```nix
# configuration.nix
{
nix.settings = {
substituters = ["https://hyprland.cachix.org"];
trusted-public-keys = ["hyprland.cachix.org-1:a7pgxzMz7+chwVL3/pzj6jIBMioiJM7ypFP8PwtkuGc="];
};
}
```

50
pages/Nvidia/_index.md Normal file
View File

@ -0,0 +1,50 @@
# Nvidia
## Foreword
There is no _official_ support for Nvidia. Unfortunately, their drivers are so messy, and their products so random, that it's impossible for us to help if these instructions don't work fully.
Every card seems to be random, and might work perfectly, or not work at all.
Nevertheless, it's recommended to at least try this tutorial.
## How to get Hyprland to possibly work on Nvidia
Install the `nvidia-dkms` driver and add it to your initram & kernel parameters, follow the information available here: [https://wiki.archlinux.org/title/NVIDIA#DRM_kernel_mode_setting](https://wiki.archlinux.org/title/NVIDIA#DRM_kernel_mode_setting)
_* Note_: If your GPU is listed as supported by the `nvidia-open-dkms` driver, go with that one instead.
Following the wrapping instructions found at [The Quick Start Page](https://github.com/hyprwm/Hyprland/wiki/Quick-start#wrapping-the-launcher-recommended), wrap the launcher and additionally export these:
```sh
export LIBVA_DRIVER_NAME=nvidia
export CLUTTER_BACKEND=wayland
export XDG_SESSION_TYPE=wayland
export QT_WAYLAND_DISABLE_WINDOWDECORATION=1
export MOZ_ENABLE_WAYLAND=1
export GBM_BACKEND=nvidia-drm
export __GLX_VENDOR_LIBRARY_NAME=nvidia
export WLR_NO_HARDWARE_CURSORS=1
export WLR_BACKEND=vulkan
export QT_QPA_PLATFORM=wayland
export GDK_BACKEND=wayland
```
Install `qt5-wayland`, `qt5ct` and `libva`. Additionally `nvidia-vaapi-driver-git` (AUR) to fix crashes in some Electron-based applications, such as Unity Hub.
Reboot your computer
Launch Hyprland with the wrapper.
It _should_ work now.
### Fixing random flickering
Do note though that this forces performance mode to be active, resulting in increased power-consumption (from 22W idle on a RTX 3070TI, to 74W).
This may not even be needed for some users, only apply these 'fixes' if you in-fact do notice flickering artifacts from being idle for ~5 seconds.
Make a new file at `/etc/modprobe.d/nvidia.conf` and paste this in:
```
options nvidia NVreg_RegistryDwords="PowerMizerEnable=0x1; PerfLevelSrc=0x2222; PowerMizerLevel=0x3; PowerMizerDefault=0x3; PowerMizerDefaultAC=0x3"
```
Reboot your computer and it should be working.

7
pages/Useful Utilities/App-Clients.md Normal file
View File

@ -0,0 +1,7 @@
# App Clients
Some clients are known for being a massive pain under Wayland. Here are great replacements for them:
## Discord
Use [WebCord](https://github.com/SpacingBat3/WebCord), it has native support for pipewire screensharing, tons of great features and tries to stay infringing as little as possible on the Discord ToS.

7
pages/Useful Utilities/App-Launchers.md Normal file
View File

@ -0,0 +1,7 @@
# App Launchers
## Wofi
wofi is a great and customizable launcher just for wayland. [SourceHut](https://hg.sr.ht/~scoopta/wofi).
## bemenu
bemenu is, maybe for some, the more well-known one. Kinda like dmenu. [GitHub](https://github.com/Cloudef/bemenu)

17
pages/Useful Utilities/Screen-Sharing.md Normal file
View File

@ -0,0 +1,17 @@
# Screen Sharing
Screensharing is done through PipeWire WebRTC on Wayland.
## Prereqs
Make sure you have `pipewire` and `wireplumber` installed, enabled and running if you don't have them yet.
Also install `slurp` for monitor selection.
## Screensharing
Read [this amazing gist by PowerBall253](https://gist.github.com/PowerBall253/2dea6ddf6974ba4e5d26c3139ffb7580) for a great tutorial.
## Caveats
You cannot screenshare separate windows with Hyprland, yet. Only full monitors.

46
pages/Useful Utilities/Status-Bars.md Normal file
View File

@ -0,0 +1,46 @@
# Status Bars
Launch your bar with `exec-once=`.
## Waybar
Waybar is a GTK status bar made specifically for wlroots compositors.
To use it, it's recommended to either use the AUR package `waybar-hyprland-git`, or compile manually with the `USE_EXPERIMENTAL` flag enabled.
To compile manually:
Clone the source, then do:
```sh
sed -i 's/zext_workspace_handle_v1_activate(workspace_handle_);/const std::string command = "hyprctl dispatch workspace " + name_;\n\tsystem(command.c_str());/g' src/modules/wlr/workspace_manager.cpp
meson --prefix=/usr --buildtype=plain --auto-features=enabled --wrap-mode=nodownload build
meson configure -Dexperimental=true build
```
and finally:
```sh
sudo ninja -C build install
```
If you want to use the workspaces module, it's called `wlr/workspaces`.
For more info regarding configuration, see [The Waybar Wiki](https://github.com/Alexays/Waybar/wiki)
## eww
In order to use [eww](https://github.com/elkowar/eww), you first have to
install it, either using your distro's package manager, by searching
`eww-wayland`, or by manually compiling. In the latter case, you need to
have `cargo` and `rustc` installed, then follow the [instructions](https://elkowar.github.io/eww).
### Configuration
After you've successfully installed eww, you can move onto configuring it.
There are a few examples listed in the [Readme](https://github.com/elkowar/eww),
we highly recommend you to also read through the
[Configuration options](https://elkowar.github.io/eww/configuration.html).
**NOTE:** Read
[the wayland section](https://elkowar.github.io/eww/configuration.html#wayland)
carefully before asking why your bar doesn't work.

15
pages/Useful Utilities/Wallpapers.md Normal file
View File

@ -0,0 +1,15 @@
# Wallpapers
Launch your wallpaper utility with `exec-once=`.
## hyprpaper
Straight from our oven, `hyprpaper` is a wallpaper utility from the Hypr Development team. See its usage and config by following the README on the [GitHub Page](https://github.com/hyprwm/hyprpaper)
## swaybg
Great utility if all you want is one simple static wallpaper that will never change, and don't want to make a config file. Get it over [here](https://github.com/swaywm/swaybg).
## wpaperd
A bit more advanced wallpaper daemon with automatic wallpaper changing options and other fancy stuff. [GitHub](https://github.com/danyspin97/wpaperd)
## mpvpaper
A neat mpv wrapper to play a video as your wallpaper. [GitHub](https://github.com/GhostNaN/mpvpaper)

15
pages/Useful Utilities/_index.md Normal file
View File

@ -0,0 +1,15 @@
# Useful utilities
This category is dedicated to short tutorials on how to get useful utilities for Hyprland working.
## List of Pages
- **[Status Bars](https://github.com/hyprwm/Hyprland/wiki/Status-Bars)**
- **[App Launchers](https://github.com/hyprwm/Hyprland/wiki/App-Launchers)**
- **[Wallpapers](https://github.com/hyprwm/Hyprland/wiki/Wallpapers)**
- **[Screen Sharing](https://github.com/hyprwm/Hyprland/wiki/Screen-Sharing)**
- **[App Clients](https://github.com/hyprwm/Hyprland/wiki/App-Clients)**