Master tutorial

If you are coming to Hyprland for the first time, this is the main tutorial to read.

This tutorial covers everything you need to get things going. It links to other pages where necessary.

Install Hyprland

See Installation and come back here once you have successfully installed Hyprland.

Install kitty (default terminal emulator). This is available in most distros’ repositories.

NVIDIA?

Please take a look at the NVIDIA page before launching. It has information regarding the needed environment and tweaks.

VM?

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 pass through a real GPU to make it work.

Please bear in mind that 3D acceleration in VMs may be pretty slow.

Launching Hyprland

Hyprland can be executed by typing start-hyprland in your TTY.

You can see some launch flags by doing start-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 SDDM version ⩾ 0.20.0 or the latest git version (or sddm-git from the AUR) to prevent SDDM bug 1476 (90s shutdowns).
• plasma-login-manager: Works flawlessly, but depends on systemd.
• GDM: Works with the caveat of crashing Hyprland on the first launch.
• greetd: Works flawlessly, especially with ReGreet.
• ly: Works flawlessly.

DE-like pre-configured setups

Do you want to just get Hyprland pre-configured like a DE, without making your own configuration from scratch?

Check out the Preconfigured setups page to see a few options.

These dotfiles should do everything for you, and have their own tutorials as well.

If you choose to use those, you can skip the next step. However, it’s still recommended to read all the points below it. They’ll give you recommended apps, replacements for old X11 software, information about configuring displays, etc.

In Hyprland with the default config

You’re good to go with your adventure, technically.

Use SUPER + Q to launch kitty. If you wish to choose the default terminal before you proceed, you can do so in ~/.config/hypr/hyprland.lua (example config).

If you want the best experience with less hassle googling, keep reading.

Monitors config

See Monitors page to learn all about configuring your displays.

Fully configure Hyprland

Head onto the Configuring page to learn all about configuring Hyprland to your liking.

Important software

See the Must-have software page for the crucial things to make Wayland/Hyprland/other apps work correctly.

Apps / X11 replacements

See the Useful utilities page about that. You can also visit the Awesome-Hyprland repository for a more comprehensive list.

Force apps to use Wayland

A lot of apps will use Wayland by default. Chromium (and other browsers based on it), as well as Electron apps, 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. If you are on NixOS, you can also set the environment variable NIXOS_OZONE_WL=1 in your configuration.

For most Electron apps, you should put the above in ~/.config/electron-flags.conf. Note that VSCode is known not to work with it.

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.

Themes

Since Hyprland is not a fully-fledged Desktop Environment, you will need to use tools such as lxappearance or nwg-look (recommended) for GTK, and hyprqt6engine for qt6 apps.

Cursors

Cursors are a notorious pain to set up when you don’t know how. See this FAQ entry on changing your mouse cursor.