Hyprland is a wlroots-based tiling Wayland compositor written in C++. Noteworthy features of Hyprland include dynamic tiling, tabbed windows, a clean and readable C++ code-base, and a custom renderer that provides window animations, rounded corners, and Dual-Kawase Blur on transparent windows. General usage and configuration is thoroughly documented at Hyprland wiki.
Install one of the following:
- - Latest upstream release.
- AUR - Latest commit to master branch.
Hyprland bundles its own version of wlroots, which closely followsAUR. This improves stability, while also avoiding dependency conflicts with other wlroots-based compositors.
NVIDIA GPU users should also make sure to follow the NVIDIA specific page on the Hyprland wiki before trying to launch Hyprland. Failure to do so will likely result in many bugs including not being able to log in, flashing windows and high CPU usage.
Configuration is done through a single config file, hyprland.conf, though it supports splitting the configuration into multiple files and including them in
hyprland.conf. If you installed Hyprland with your package manager, it is likely in
/usr/share/hyprland/hyprland.conf and, after logging in for the first time,
~/.config/hypr/hyprland.conf. If you installed from source, it is in the Hyprland cloned repository. Copy
hyprland.conf includes directives to configure your devices (monitors, keyboards, mice, trackpads), as well as settings for animations, decorations, layout, etc. You can set key bindings, window rules, and execute commands (once or each time the config is reloaded).
The config is automatically reloaded each time you update the file. You can also use
hyprctl reload for the same effect. For some settings (particularly input settings), you may have to restart your Hyprland session.
Settings can also be changed on the fly with
hyprctl but they will not be saved.
Configuration is documented in the Hyprland wiki.
Setting screen resolution
Hyprland will try to detect your screen resolution automatically however in some cases it will fail and default to a failsafe, usually if there are multiple screens present or if you have a hybrid laptop. If everything on your screen is huge then you need to define your default monitor and resolution in
First find your default monitor using
$ hyprctl monitors
Monitor eDP-1 (ID 0): firstname.lastname@example.org at 0x0 description: Chimei Innolux Corporation 0x153C (eDP-1) make: Chimei Innolux Corporation model: 0x153C serial: active workspace: 2 (2) special workspace: 0 () reserved: 0 32 0 0 scale: 1.00 transform: 0 focused: yes dpmsStatus: 1 vrr: 0
Then add your monitor to
... monitor=eDP-1,1920x1080@144,0x0,1 ...
- You should adjust eDP-1 and 1920x1080@144 to suit your own display.
- 0x0 is a position offset used for multi screen setups and the final 1 is the screen scaling factor.
Turning off the screen using DPMS after a timeout period
Hyprland has a built in dispatcher to handle DPMS requests however using it as a direct keybind is not recommended, doing so will result in you not being able to turn the screen back on and will require you to reboot.
Instead you should install and then call a script in your Hyprland configuration file, something like the following works:
$ [ ! -d "~/.config/hypr/scripts" ] && mkdir ~/.config/hypr/scripts
swayidle -w timeout 300 'swaylock -f -c 000000' \ timeout 600 'hyprctl dispatch dpms off' \ timeout 900 'systemctl suspend' \ resume 'hyprctl dispatch dpms on' \ before-sleep 'swaylock -f -c 000000' &
$ chmod +x ~/.config/hypr/scripts/sleep.sh
... exec-once = ~/.config/hypr/scripts/sleep.sh ...
Stop sleeping while using applications
The above setup will result in your monitor powering off while you are doing things like playing a game, watching a video or listening to music where you might not touch the system for longer than the timeout period.
To fix this you can either use Hyprlands built in Window Rules V2 function which has a
idleinhibit rule or you can install one of either AUR or AUR. The former uses D-Bus to prevent Swayidle requests whenever Firefox or Chromium are playing audio/video. The latter prevents Swayidle requests whenever any application is playing audio.
It is currently recommended to start Hyprland from a TTY.
While launching from a display manager is not officially supported, users have reported success launching from GDM, SDDM, and others. The package contains a display manager entry, and all Hyprland AUR packages will generate one automatically. If manually installing from source, an example
Hyprland.desktop file is provided in the example directory of the source code, which may be copied to
/usr/share/wayland-sessions/ to provide a display manager entry.
Both methods provide identical results, plus or minus a few environment variables and services.
hyprctl and IPC
hyprctl is a command line utility that comes installed with Hyprland to communicate with the display server. It allows you to dispatch commands to the server (equivalent to commands in the configuration file, but with a slightly different syntax), set keywords, send queries and request information. See the full documentation.
Hyprland also exposes 2 UNIX Sockets, for controlling and getting information about Hyprland via code or command-line utilities. These sockets broadcast events on focus change (windows, workspaces, monitors), creation of windows/workspace, and so on.
Both hyprctl and the IPC sockets can be effectively used in scripts to control Hyprland for complex tasks.
As a wlroots-based compositor, Hyprland can utilize xdg-desktop-portal.to enable screen capture in a range of applications by way of
Flickering on NVIDIA cards
This is a known issue on NVIDIA. You can useAUR or AUR instead for a better experience.
xdg-desktop-portal-hyprland is using a lot of CPU
This bug is caused when using an NVIDIA GPU without the
nvidia_drm.modeset=1 kernel parameter.