---
title: Hyprland Post Install Setup & Keybinds
description: Common tasks to do after installation and keybinds overview
---

import { Kbd } from 'starlight-kbd/components'
import ImageComponent from '~/components/image-component.astro';
import { Aside } from '@astrojs/starlight/components';

:::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](https://github.com/Jinra)**

For Noctalia related issues please take a look at the [Noctalia docs](https://docs.noctalia.dev/).

## 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/). A default block is made for you, you can add more for additional monitors.
  * `output` edit `variables.lua` instead with the monitor value; you can run `hyprctl monitors` to get this id (e.g. `DP-1`). If you add more monitors use MONITOR2, MONITOR3, etc and add them to `variables.lua` as well.
  * `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 may 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) | <Kbd linux="Super+Escape" /> |
| Close focused window/app | <Kbd linux="Super+Q" /> |
| Toggle floating/tiled | <Kbd linux="Super+Alt+Space" /> |
| Maximize focused window | <Kbd linux="Super+D" /> |
| Fullscreen focused window | <Kbd linux="Super+F" /> |
| Toggle split direction | <Kbd linux="Super+J" /> |
| Focus left | <Kbd linux="Super+Left" /> |
| Focus right | <Kbd linux="Super+Right" /> |
| Focus up | <Kbd linux="Super+Up" /> |
| Focus down | <Kbd linux="Super+Down" /> |
| Switch window focus on workspace | <Kbd linux="Alt+Tab" /> |
| Open window switcher | <Kbd linux="Super+Tab" /> |
| Move focused window to monitor | <Kbd linux="Super+Shift+#" /> |
| Move focused window to workspace | <Kbd linux="Super+Shift+Control+#" /> |
| Move focused window to special workspace | <Kbd linux="Super+Shift+S" /> |
| Move focused window right | <Kbd linux="Super+Shift+Right" /> |
| Move focused window left | <Kbd linux="Super+Shift+Left" /> |
| Move focused window up | <Kbd linux="Super+Shift+Up" /> |
| Move focused window down | <Kbd linux="Super+Shift+Down" /> |
| Move focused window to next workspace | <Kbd linux="Super+Control+Shift+Right" /> |
| Move focused window to previous workspace | <Kbd linux="Super+Control+Shift+Left" /> |
| Move focused window to previous workspace (mouse) | <Kbd linux="Super+Control+Shift+Scroll&nbsp;up" /> |
| Move focused window to next workspace (mouse) | <Kbd linux="Super+Control+Shift+Scroll&nbsp;down" /> |
| Move focused window to next monitor | <Kbd linux="Super+Shift+Scroll&nbsp;down" /> |
| Move focused window to previous monitor | <Kbd linux="Super+Shift+Scroll&nbsp;up" /> |
| Move window (mouse) | <Kbd linux="Super+Left&nbsp;Click" /> |
| Resize window (mouse) | <Kbd linux="Super+Right&nbsp;Click" /> |

### Launcher

| Description | Key |
|-------------|-----|
| Open Terminal | <Kbd linux="Super+Return" /> |
| Open File Manager | <Kbd linux="Super+E" /> |
| Open Editor | <Kbd linux="Super+T" /> |
| Open Calculator | <Kbd linux="Super+C" /> |
| Open Browser | <Kbd linux="Super+W" /> |
| Open System Monitor (btop) | <Kbd linux="Control+Shift+Escape" /> |
| Toggle Noctalia Settings | <Kbd linux="Super+Z" /> |
| Toggle Control Center | <Kbd linux="Super+X" /> |
| Toggle App Launcher | <Kbd linux="Super+Space" /> |
| Open Emoji Launcher | <Kbd linux="Super+period" /> |
| Lock screen | <Kbd linux="Super+L" /> |
| Toggle session menu | <Kbd linux="Super+Alt+C" /> |

### Hardware Controls

| Description | Key |
|-------------|-----|
| Raise Volume | <Kbd linux="Volume Up" /> |
| Lower Volume | <Kbd linux="Volume Down" /> |
| Mute Audio Output | <Kbd linux="Mute" /> |
| Mute Microphone Input | <Kbd linux="MicMute" /> |
| Play/Pause Media | <Kbd linux="Play" /> / <Kbd linux="Pause" /> |
| Next Media Track | <Kbd linux="Next" /> |
| Previous Media Track | <Kbd linux="Previous" /> |
| Increase Screen Brightness | <Kbd linux="Brightness Up" /> |
| Decrease Screen Brightness | <Kbd linux="Brightness Down" /> |

### Utilities

| Description | Key |
|-------------|-----|
| Color Picker | <Kbd linux="Super+P" /> |
| Screen Capture & Annotate | <Kbd linux="Print" /> |
| Screen Capture Window & Annotate (v4) | <Kbd linux="Super+Print" /> |
| Screen Capture Monitor & Annotate (v5) | <Kbd linux="Super+Print" /> |
| Toggle Screen Recorder (v4 only) | <Kbd linux="Super+R" /> |
| Toggle Wallpaper Menu | <Kbd linux="Super+Shift+W" /> |
| Open Clipboard History | <Kbd linux="Super+V" /> |
| Toggle Notification History | <Kbd linux="Super+A" /> |
| Zoom In | <Kbd linux="Super+Plus" /> |
| Zoom Out | <Kbd linux="Super+Minus" /> |

### Workspaces & Monitors

| Description | Key |
|-------------|-----|
| Switch to workspace [1-10] | <Kbd linux="Super+[0-9]" /> |
| Move window to workspace [1-10] (follow) | <Kbd linux="Super+Shift+[0-9]" /> |
| Move window to workspace [1-10] (don't follow) | <Kbd linux="Super+Alt+[0-9]" /> |
| Focus workspace (Relative) | <Kbd linux="Super+Control+#" /> |
| Focus workspace (Absolute) | <Kbd linux="Super+Alt+#" /> |
| Focus next workspace | <Kbd linux="Super+Control+Right" /> |
| Focus previous workspace | <Kbd linux="Super+Control+Left" /> |
| Focus first empty workspace | <Kbd linux="Super+Control+Down" /> |
| Focus next workspace (mouse) | <Kbd linux="Super+Control+Scroll&nbsp;down" /> |
| Focus previous workspace (mouse) | <Kbd linux="Super+Control+Scroll&nbsp;up" /> |
| Focus next monitor (mouse) | <Kbd linux="Super+Scroll&nbsp;down" /> |
| Focus previous monitor (mouse) | <Kbd linux="Super+Scroll&nbsp;up" /> |
| Toggle special workspace (scratchpad) | <Kbd linux="Super+S" /> |

## 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.
1. 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).
1. 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!)
1. 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](https://github.com/noctalia-dev/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`.
1. Reboot and select the Hyprland (UWSM) session from your display manager.
    * If the shell fails to load, try rebooting once more. 
1. Log in and follow the [Post Setup Tasks](/configuration/desktop_environments/hyprland/#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).
1. Run `meld /etc/skel/.config/hypr ~/.config/hypr`.
1. From meld you will see an overview of all the files with changes. Blue files have changes, while green files are net new.
    <br />
    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/meld_overview.png')} />
1. 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.
    <Aside type="note">Make sure to not overwrite things you may have changed such as your monitor settings.</Aside>
    <br />
    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/merge.png')} />
1. You can merge all as well.
    <br />
    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/merge_all_1.png')} />
    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/merge_all_2.png')} />
1. When you're finished with your changes for the file, save and exit.
    <br />
    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/save_exit.png')} />
1. 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.
    <br />
    <ImageComponent imgsrc={import('~/assets/images/v4-v5-migration/workspaces.png')} />

### 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.
1. `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.

## FAQ

> _"Why doesn't my clipboard history persist through reboots?"_

You need to setup a secrets store for this to work properly. Kwallet is installed by default but you can also use gnome-keyring or another secrets store. If you want to use kwallet, install `kwalletmanager` from the repo, then open it and create a new wallet. It's easiest to make the password blank, but you can also setup auto unlock with your display manager, which is outside the scope of this wiki; see the [Arch wiki](https://wiki.archlinux.org/title/KDE_Wallet#Configuration) for more details. After setting up a wallet, initialize it in your `autostart.lua` file with `hl.exec_cmd("kwalletd6")`.

> "_How do I not have satty pop up after taking a screenshot?_"

You can easily dismiss satty by pressing ctrl + s to save your screenshot or ctrl + c to copy. If you don't want satty to pop up at all, you can configure the setting to copy to clipboard or save to file in Noctalia settings > shell > screenshot.

> _"How do I change my keyboard input?"_

Edit `inputs.lua` and add `kb_layout`. See [here](https://wiki.hypr.land/Configuring/Basics/Variables/#input).

> _"Why are some theming options (Dolphin icons, some QT elements, etc.) not working?"_

Cachy's default repo only provides `qt6ct` (QT6 Configuration Tool). However, there is another tool that works better for Plasma QT applications like dolphin, gwenview, etc. Download `qt6ct-kde` from the AUR instead and apply the Noctalia theme with it. This should have your plasma apps theme better in Hyprland.

> _"How do I change my default browser?"_

Run `xdg-settings set default-web-browser your_browser.desktop`. You can find your browser's desktop file name by running `ls /usr/share/applications/`.
