Hyprland Post Install Setup & Keybinds

Note

Hyprland is a wayland compositor that supports various layouts such as dwindle (tiling), scrolling, master, monocle, and custom layouts. It is not a full desktop environment (DE).

Why use Hyprland?

Hyprland is a beautiful dynamic tiling manager that offers a variety of layouts and advanced compositor functionality such as VRR, tearing, and HDR. The CachyOS dots for Hyprland are setup with general defaults that should be completely usable out of the box, with applications that follow the general system theme.

Dotfiles maintained by Jinra

For Noctalia related issues please take a look at the Noctalia docs.

Post Setup Tasks

You will want to configure a few user-specific things after setup. For additional settings, please refer to the Hyprland wiki https://wiki.hypr.land/Configuring/Start/

Location ~/.config/hypr/config

• monitors.lua will setup your monitors. (see more at https://wiki.hypr.land/Configuring/Basics/Monitors/)
  • output should be your monitor id; you can run hyprctl monitors to get this id (e.g. DP-1).
  • mode should be in a format such as 1920x1080@60 (horizontal x vertical @ refresh rate).
  • scale You will most likely want 1, but may want this value higher for higher resolution monitors.
  • You will need to reboot after the first adjustment, but future adjustments should be reflected live.
• variables.lua
  • Add your monitor assignments here. your PRIMARY_MONITOR and MONITOR1 should generally be the same monitor. You can remove/add MONITOR# variables as needed.
  • Define your number of workspaces per monitor. Do not exceed 10.
• input.lua You can define your various hypr input settings here. You’ll probably want to adjust the sensitivity.
• binds.lua Review this file to see all the keybinds for these dots. You can also check out the general overview below.
• windowrules.lua If you find yourself wondering why certain windows have certain behaviors check this file; you can also add/remove rules as you see fit.
• workspaces.lua Add various workspace settings here. It’s recommended to add 3 workspaces per monitor (as shown in the examples) plus the gaming workspace to the primary monitor.
• environment.lua is used for setting hypr or user specific environmental variables. Not required to adjust if you’re using UWSM, and it’s more preferable to add these to the UWSM env file instead (see below).

Location ~/.config/uwsm

• env is a file used for defining global variables, you can use this for general variables that need to be assigned for your specific user account (Examples: HYPRCURSOR_THEME, XCURSOR_THEME, QT_QPA_PLATFORM, etc.)

Location ~/.config/noctalia (V5 only; V4 will have files here, but you do not need to touch them as they can be configured through Noctalia settings)

• config.toml this is where default configuration for cachyos-hypr-noctalia lives. If you’re wondering why the defaults differ from a vanilla noctalia v5 installation, this is why. You shouldn’t have to touch anything in this file.

Location noctalia settings (Super + Z)

• You can edit Noctalia settings here. It’s recommended to go to the templates section and turn on any color templates for any apps you may use.
• Also check out the plugins store for useful official and community plugins.

Keybinds

Most of the key combinations require the use of the mod key which in our case is the Windows/Command key (referenced as SUPER), you can change it in binds.lua.

Window Management

Description	Key
Force close app/window (hold combo and click)	Super + EscapeSuperEscape
Close focused window/app	Super + QSuperQ
Toggle floating/tiled	Super + Alt + SpaceSuperAltSpace
Maximize focused window	Super + DSuperD
Fullscreen focused window	Super + FSuperF
Toggle split direction	Super + JSuperJ
Focus left	Super + Left ArrowSuperLeft
Focus right	Super + Right ArrowSuperRight
Focus up	Super + Up ArrowSuperUp
Focus down	Super + Down ArrowSuperDown
Switch window focus on workspace	Alt + TabAltTab
Open window switcher	Super + TabSuperTab
Move focused window to monitor	Super + Shift + Number SignSuperShift#
Move focused window to workspace	Super + Shift + Control + Number SignSuperShiftControl#
Move focused window to special workspace	Super + Shift + SSuperShiftS
Move focused window right	Super + Shift + Right ArrowSuperShiftRight
Move focused window left	Super + Shift + Left ArrowSuperShiftLeft
Move focused window up	Super + Shift + Up ArrowSuperShiftUp
Move focused window down	Super + Shift + Down ArrowSuperShiftDown
Move focused window to next workspace	Super + Control + Shift + Right ArrowSuperControlShiftRight
Move focused window to previous workspace	Super + Control + Shift + Left ArrowSuperControlShiftLeft
Move focused window to previous workspace (mouse)	Super + Control + Shift + Scroll upSuperControlShiftScroll up
Move focused window to next workspace (mouse)	Super + Control + Shift + Scroll downSuperControlShiftScroll down
Move focused window to next monitor	Super + Shift + Scroll downSuperShiftScroll down
Move focused window to previous monitor	Super + Shift + Scroll upSuperShiftScroll up
Move window (mouse)	Super + Left ClickSuperLeft Click
Reize window (mouse)	Super + Right ClickSuperRight Click

Launcher

Description	Key
Open Terminal	Super + ReturnSuperReturn
Open File Manager	Super + ESuperE
Open Editor	Super + TSuperT
Open Calculator	Super + CSuperC
Open Browser	Super + WSuperW
Open System Monitor (btop)	Control + Shift + EscapeControlShiftEscape
Toggle Noctalia Settings	Super + ZSuperZ
Toggle Control Center	Super + XSuperX
Toggle App Launcher	Super + SpaceSuperSpace
Open Emoji Launcher	Super + periodSuperperiod
Lock screen	Super + LSuperL
Toggle session menu	Super + Alt + CSuperAltC

Hardware Controls

Description	Key
Raise Volume	Volume then Up ArrowVolume Up
Lower Volume	Volume then Down ArrowVolume Down
Mute Audio Output	MuteMute
Mute Microphone Input	MicMuteMicMute
Play/Pause Media	PlayPlay / PausePause
Next Media Track	NextNext
Previous Media Track	PreviousPrevious
Increase Screen Brightness	Brightness then Up ArrowBrightness Up
Decrease Screen Brightness	Brightness then Down ArrowBrightness Down

Utilities

Description	Key
Color Picker	Super + PSuperP
Screen Capture & Annotate	PrintPrint
Screen Capture Window & Annotate (v4)	Super + PrintSuperPrint
Screen Capture Monitor & Annotate (v5)	Super + PrintSuperPrint
Toggle Screen Recorder (v4 only)	Super + RSuperR
Toggle Wallpaper Menu	Super + Shift + WSuperShiftW
Open Clipboard History	Super + VSuperV
Toggle Notification History	Super + ASuperA

Workspaces & Monitors

Description	Key
Switch to workspace [1-10]	Super + [0-9]Super[0-9]
Move window to workspace [1-10] (follow)	Super + Shift + [0-9]SuperShift[0-9]
Move window to workspace [1-10] (don’t follow)	Super + Alt + [0-9]SuperAlt[0-9]
Focus workspace	Super + Control + Number SignSuperControl#
Focus next workspace	Super + Control + Right ArrowSuperControlRight
Focus previous workspace	Super + Control + Left ArrowSuperControlLeft
Focus first empty workspace	Super + Control + Down ArrowSuperControlDown
Focus next workspace (mouse)	Super + Control + Scroll downSuperControlScroll down
Focus previous workspace (mouse)	Super + Control + Scroll upSuperControlScroll up
Focus next monitor (mouse)	Super + Scroll downSuperScroll down
Focus previous monitor (mouse)	Super + Scroll upSuperScroll up
Toggle special workspace (scratchpad)	Super + SSuperS

Migrating from another DE/WM

If you already have another DE/WM installed, you can migrate to this dots with the instructions below.

Note

While it’s possible to use the same user account with Hyprland, it’s highly recommended to create a new user account (instructions included). Additionally, even with a new user account, there may be daemon conflicts with your previous DE/WM, so it’s more ideal to use a single environment.

Make sure to replace the variables in angle brackets (<>) below including the angle brackets themselves.

1. Run sudo pacman -S cachyos-hypr-noctalia. If you run into a package conflict with another -settings package (such as cachyos-kde-settings), you can delete the conflicting package as these packages do not affect current users.
2. To create a new user run sudo useradd -m <new_user> -s /bin/fish. You can also use another shell if you prefer (i.e. /bin/zsh).
3. Run sudo passwd <new_user> to set a password for the account.
   • If you really want to use the same account (highly discouraged), instead copy the dots over to the user folder cp -r /etc/skel/. ~ (make sure to create a backup/snapshot first!)
4. Optionally install noctalia-greeter or sddm as your display manager. noctalia-greeter integrates better with Noctalia, but setup is slightly more complicated.
   • To enable sddm as your display manager, install it with sudo pacman -Syu sddm, then run systemctl disable display-manager and systemctl enable sddm.
   • To install Noctalia Greeter, run sudo pacman -Syu noctalia-greeter, and follow the “Setting up greetd” section of the linked doc. Afterwards, run systemctl disable display-manager and systemctl enable greetd.
5. Reboot and select the Hyprland (UWSM) session from your display manager.
   • If the shell fails to load, try rebooting once more.
6. Log in and follow the Post Setup Tasks.

Migrating from v4 dots to V5 / Updating your dots

If you’re currently using cachyos-hypr-noctalia with Noctalia v4 and have updated from package version 1.0 to a newer version, or want to update your dots, follow the instructions below. See full change logs in the release to determine if you should update your dots. https://github.com/CachyOS/cachyos-hypr-noctalia/releases

Hypr updates

Note

Once you migrate your keybinds from v4 to v5, they will no longer work to call Noctalia IPC calls.

1. Install meld if you don’t have it (pacman -Q meld to check if you have it).
2. Run meld /etc/skel/.config/hypr ~/.config/hypr.
3. From meld you will see an overview of all the files with changes. Blue files have changes, while green files are net new.
   
4. Click into a blue file to see changes to be applied. You can use your best judgement to determine what to apply, but if you haven’t made any changes, it’s safe to overwrite the whole file. Click the arrow to apply changes and the x to remove old lines.

   Nota

   Make sure to not overwrite things you may have changed such as your monitor settings.
   
   
5. You can merge all as well.
   
6. When you’re finished with your changes for the file, save and exit.
   
7. The net new green files will ask where you want to save it. You can save it in ~/.config/hypr/config/ with the same name. There are 4 new files.
   • defaults.lua is now variables.lua. You must manually move any custom additions/changes to the new file.
   • keybinds.lua is now binds.lua. You must manually move any custom additions/changes to the new file.
   • input.lua is now inputs.lua. You must manually move any custom additions/changes to the new file.
   • workspaces.lua is new net and can be cleanly moved over without changes.
   
   

Noctalia Updates

1. Run rm -rf ~/.config/noctalia to remove the current configurations. Alternatively, move them somewhere else if you think you may need something there.
2. cp -r /etc/skel/.config/noctalia ~/.config will copy the new configuration into your home folder.

Note

The only important file is config.toml, so you can copy that individually instead of deleting and replacing the whole folder when the package updates if you want.

Other Updates

Other files may have updates, you can use meld to integrate these. See the full release change log to see what else may have changed.

Removing orphans (v4->v5 migration)

After updating the package, old dependencies will be orphaned, you can remove those by running shelly purify -o.

Reboot

Rebooting should make the changes take effect. If the shell fails to load, try rebooting once more.