Master Tutorial
If you are coming to Hyprland for the first time, this is the main tutorial to read.
Due to a lot of people doing stupid stuff, this tutorial will cover literally everything you need to just get things going. It does link to other pages where necessary.
See Installation and come back here once you have successfully installed Hyprland.
Install kitty (default terminal emulator) terminal. This is available in most
distros’ repositories.
If not using an NVIDIA card, skip this step
Please take a look at The Nvidia page before launching. It has a lot of info regarding the needed environment and tweaks.
If not using a VM, skip this step
In a VM, make sure you have 3D acceleration enabled in your virtio config (or virt-manager) otherwise Hyprland will not work.
You can also passthru a GPU to make it work.
Please bear in mind 3D accel in VMs may be pretty slow.
Now, you can just execute Hyprland in your tty.
!IMPORTANT: Do not launch Hyprland with root permissions (don’t
sudo)
You can see some launch flags by doing Hyprland -h, these include setting the config
path, ignoring a check for the above, etc.
Login managers are not officially supported, but here’s a short compatibility list:
- SDDM → Works flawlessly. Install the latest git version (or sddm-git from the AUR if you use Arch) to prevent SDDM bug 1476 (90s shutdowns).
- GDM → Works with the caveat of crashing Hyprland on the first launch
- ly → Works poorly
You’re good to go with your adventure, technically.
Use ~/.config/hypr/hyprland.conf.
If you want the best experience with less hassle googling, keep reading.
See the Must-have Software page for the crucial things to make Wayland / Hyprland / other apps work correctly.
See Configuring Hyprland page to learn all about configuring your displays.
See the Useful Utilities page and the Sway wiki page just about that. You can also visit the Awesome-Hyprland repository for a more comprehensive list.
Head onto the Configuring Hyprland page to learn all about configuring Hyprland to your likings.
Cursors are a notorious pain to set up when you don’t know how. See this FAQ entry
If your cursor does not appear, then see this FAQ entry
Since this is not a full fledged Desktop Environment, you will need to use tools such as
lxappearance and nwg-look (recommended) for GTK, and qt5ct / qt6ct for their
respective QT versions. Some older applications may also require qt4ct.
A lot of apps will use Wayland by default. Chromium (and other browsers based on it or electron)
don’t. You need to pass --enable-features=UseOzonePlatform --ozone-platform=wayland to them or use .conf files
where possible. Chromium-based browsers also should have a toggle in chrome://flags. Search for “ozone” and select Wayland.
For most electron apps, you should put the above in ~/.config/electron-flags.conf. VSCode is known
to not work with that though.
A few more environment variables for forcing Wayland mode are documented here.
You can check whether an app is running in xwayland or not with hyprctl clients.