Hyprland
hyprland is an open-source wlroots-based Wayland compositor written in C++. The rendering backend is GLES 3.2.[1]
Installation
USE flags
USE flags for gui-wm/hyprland A dynamic tiling Wayland compositor that doesn't sacrifice on its looks
X | Add support for X11 |
legacy-renderer | Enable legacy renderer |
systemd | Enable use of systemd-specific libraries and features like socket activation or session tracking |
Emerge
root #
emerge --ask gui-wm/hyprland
Configuration
To view all available configuration options, run:
user $
man Hyprland
or visit the Hyprland wiki link above.
Files
Each user running Hyprland can edit the default configuration file in order to run a customized session. The default config file location is ~/.config/hypr/hyprland.conf.
Display configuration
Display options can be queried with:
user $
hyprctl monitors
Monitors can be adjusted by modifying ~/.config/hypr/hyprland.conf. Once the file is saved, the configuration is reloaded automatically.
~/.config/hypr/hyprland.conf
auto configuration of monitorsmonitor = , preferred, auto, 1
~/.config/hypr/hyprland.conf
Configure primary display which is centeredmonitor = eDP-1, 2560x1440@165.003006, 0x0, 1
~/.config/hypr/hyprland.conf
Configure alternate display which is verticalmonitor = eDP-1, 2560x1440@165.003006, 0x0, 1, transform, 1
See Monitors (Hyprland wiki) for more information.
Sound volume
If pulseaudio is being used, the following configuration can be used for changing sound volume:
~/.config/hypr/hyprland.conf
Set keyboard shortcuts to change sound volume for pulseaudiobind = , XF86AudioRaiseVolume, exec, pactl set-sink-volume @DEFAULT_SINK@ +5%
bind = , XF86AudioLowerVolume, exec, pactl set-sink-volume @DEFAULT_SINK@ -5%
If PipeWire is being used, the following configuration can be used for changing sound volume (with Wireplumber):
~/.config/hypr/hyprland.conf
Set keyboard shortcuts to change sound volume for PipeWirebind = , XF86AudioRaiseVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+
bind = , XF86AudioLowerVolume, exec, wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
If ALSA is being used, the following configuration can be used for changing the sound volume:
~/.config/hypr/hyprland.conf
Set keyboard shortcuts to change sound volume for ALSAbind = , XF86AudioRaiseVolume, exec, amixer -Mq set Speaker 5%+
bind = , XF86AudioLowerVolume, exec, amixer -Mq set Speaker 5%-
If media-sound/sndio is being used, the following configuration can be used for changing the sound volume:
~/.config/hypr/hyprland.conf
Set keyboard shortcuts to change sound volume for sndiobind = , XF86AudioRaiseVolume, exec, sndioctl -f snd/default output.level=+0.05
bind = , XF86AudioLowerVolume, exec, sndioctl -f snd/default output.level=-0.05
Other special hotkeys
~/.config/hypr/hyprland.conf
Set the keyboard shortcuts for muting mic and sound volume for pulseaudiobind = , XF86AudioMute, exec, pactl set-sink-mute @DEFAULT_SINK@ toggle
bind = , XF86AudioMicMute, exec, pactl set-source-mute @DEFAULT_SOURCE@ toggle
Monitor and keyboard backlights
The package app-misc/brightnessctl is available in GURU and can be used to adjust backlights and brightness.
root #
emerge --ask app-misc/brightnessctl
Here is an example config for monitor backlight control:
~/.config/hypr/hyprland.conf
Set keyboard shortcuts for screen brightness supportbind = , XF86MonBrightnessDown, exec, brightnessctl set 5%-
bind = , XF86MonBrightnessUp, exec, brightnessctl set 5%+
Here is an example config for keyboard backlight control:
~/.config/hypr/hyprland.conf
Set keyboard shortcuts for keyboard brightness supportbind = , xf86KbdBrightnessUp, exec, brightnessctl -d *::kbd_backlight set +33%
bind = , xf86KbdBrightnessDown, exec, brightnessctl -d *::kbd_backlight set 33%-
Other tools to control brightness include sys-power/acpilight and dev-libs/light.
Playerctl
media-sound/playerctl can be used to control multimedia apps.
root #
emerge --ask media-sound/playerctl
Here is an example config:
~/.config/hypr/hyprland.conf
Set keyboard shortcuts for media playbackbind = , XF86AudioPlay, exec, playerctl play-pause
bind = , XF86AudioNext, exec, playerctl next
bind = , XF86AudioPrev, exec, playerctl previous
bind = , XF86audiostop, exec, playerctl stop
Terminal emulator
Terminal emulators that support Wayland can be found on the Wayland Desktop Landscape page. Popular choices include x11-terms/alacritty or x11-terms/kitty, which works natively with Wayland if the KITTY_ENABLE_WAYLAND
environment variable is set to 1
.
Executing Hyprland
systemd automatically starts a dbus user session. systemd users should omit dbus-run-session
Some display managers may work. Without a display manager, Hyprland can be started from a tty:
user $
dbus-run-session Hyprland
Omitting the dbus-run-session may cause runtime errors.
On login with tty
This is a simple function that can be added to a user's shell profile file which is only evaluated in login shells, to execute a Hyprland session upon login.
~/.bash_profile
Launch Hyprland after logging into a TTYdbus-run-session Hyprland
This example is for bash, for zsh put it in ~/.zprofile.
Status bars
See Wayland Desktop Landscape for a list of status bar options.
Screen sharing
XDPH is not necessary. Hyprland will work with XDPW, but XDPH has more features, like window sharing. XDPH will work on other wlroots-based compositors, but is limited to XDPW features (others will be disabled).
xdg-desktop-portal-hyprland
xdg-desktop-portals are helper programs for desktop environments. They work by managing D-Bus interfaces and exposing them as 'portals'. On Wayland they are often needed because, unlike X, Wayland does not allow windows to easily talk to each other. If some programs start up very slowly or screen sharing does not work, a problem with the xdg-desktop-portal is likely the reason. Hyprland works with gui-libs/xdg-desktop-portal-wlr, but also lacks screen sharing. Hyprland upstream forked xdg-desktop-portal-wlr into gui-libs/xdg-desktop-portal-hyprland (available in GURU),
root #
emerge --ask gui-libs/xdg-desktop-portal-hyprland
xdg-desktop-portal-hyprland needs to be started after Hyprland starts. This is done best with Hyprland's exec-once function. It is also a good idea to tell D-Bus that the current desktop is Hyprland. To do so, add this to the Hyprland config file:
~/.config/hypr/hyprland.conf
XDPH environment variablesenv = XDG_CURRENT_DESKTOP, Hyprland
env = XDG_SESSION_TYPE, wayland
env = XDG_SESSION_DESKTOP, Hyprland
exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
OpenRC users should not worry too much about the --systemd
flag here. The command will update the systemd --user environment if possible, but will simply not do that on OpenRC.
systemd will automatically start xdg-desktop-portals along dbus. systemd users may omit this step.
Also a script should be executed at start to start xdg-desktop-portal-hyprland.
~/.config/hypr/hyprland.conf
exec-once = ~/.config/hypr/xdg-portal-hyprland
The script can reside anywhere, here it is in ~/.config/hypr/xdg-portal-hyprland
~/.config/hypr/xdg-portal-hyprland
#!/bin/bash
sleep 1
killall xdg-desktop-portal-hyprland
killall xdg-desktop-portal-gnome
killall xdg-desktop-portal-wlr
killall xdg-desktop-portal
logger 'killed all xdg-desktop'
sleep 1
/usr/libexec/xdg-desktop-portal-hyprland &
logger 'xdg-desktop-portal-hyprland started'
sleep 2
/usr/libexec/xdg-desktop-portal &
logger 'xdg-desktop-portal started'
This will ensure that no other desktop portal is running while using Hyprland, which can cause problems.
xdg-desktop-portal-gnome
Avoiding gnome-shell would be wiser than following the directions in this section. Continuing will not be supported by Gentoo.
Even though the other portals' processes get killed in the script from the earlier point, xdg-desktop-portal-gnome causes problems with Hyprland. Hyprland warns about that at startup when it detects xdg-desktop-portal-gnome on the system. When using Hyprland, xdg-desktop-portal-gnome should be uninstalled from the system:
root #
emerge --unmerge xdg-desktop-portal-gnome
Gnome will still work, but it could lack some functionality (like screen sharing).
Because gnome-base/gnome-shell depends on the portal, sys-apps/xdg-desktop-portal-gnome will be pulled in with every portage world set update. Portages package.provided feature could be used to prevent pulling in xdg-desktop-portal-gnome.
Flatpak portals
xdg-desktop-portals
xdg-desktop-portals were originally designed to provide access to system resources within flatpak sandboxes. Recently, large compositors have influenced many software developers to adopt these portals as standard mechanisms for screenshot and screencast functionalities in Wayland.
To ensure that links within flatpak applications can be opened, and flatpak applications can send notification, it's not enough to only have the gui-libs/xdg-desktop-portal-hyprland package installed. This is a fork of gui-libs/xdg-desktop-portal-wlr, which only claims to support screencast and screenshot functionalities.
For more context, refer to xdg-desktop-portal-wlr issue #42. It shows that we need to install the sys-apps/xdg-desktop-portal-gtk package and start it with hyprland.
systemd will automatically start xdg-desktop-portal along with dbus. systemd users may omit this step.
If ~/.config/hypr/xdg-portal-hyprland was added, modify it as follows:
~/.config/hypr/xdg-portal-hyprland
#!/bin/bash
sleep 1
killall xdg-desktop-portal-hyprland
killall xdg-desktop-portal-gtk
killall xdg-desktop-portal-gnome
killall xdg-desktop-portal-wlr
killall xdg-desktop-portal
logger 'killed all xdg-desktop'
sleep 1
/usr/libexec/xdg-desktop-portal-gtk &
logger 'xdg-desktop-portal-gtk started'
sleep 1
/usr/libexec/xdg-desktop-portal-hyprland &
logger 'xdg-desktop-portal-hyprland started'
sleep 2
/usr/libexec/xdg-desktop-portal &
logger 'xdg-desktop-portal started'
Using Vulkan
Since the update of hyprland to 0.40, it's broken.
See: ArchLinux BBS, Hyprland issue 5996
Since the update of amdgpu-pro-vulkan to 23.10.3.1620044, this is no longer an issue. The information below is kept in case it recurs with future updates.
Vulkan is not currently officially supported by Hyprland.[2] However, use of env = WLR_RENDERER,vulkan
in hyprland.conf
has worked well for some time. Recent updates to the Vulkan SDK/loader or perhaps wlroots resulted recently in Hyprland being unable to launch with this environmental variable on systems where both media-libs/mesa and media-libs/amdgpu-pro-vulkan are present, perhaps because the latter currently lags behind the former in terms of Vulkan version.
One way to see which versions of Vulkan are available/being used is to run:
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/radeon_icd.x86_64.json fastfetch --gpu-force-vulkan
and
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/amd_pro_icd64.json fastfetch --gpu-force-vulkan
and compare the output of the listed Vulkan versions. One will say "radv" and the other will say "AMD proprietary driver".
The issue at present which prevents Hyprland from launching is that the AMD proprietary driver is defaulted to. To fix that, place env = VK_ICD_FILENAMES,/usr/share/vulkan/icd.d/radeon_icd.x86_64.json
in hyprland.conf
on the line before env = WLR_RENDERER,vulkan
. Then Hyprland will be able to start using the Mesa radv driver. This was tested on Hyprland 0.27.2-r1, Mesa 23.0.3-r1, and amdgpu-pro-vulkan 22.20.3.1462318.
Removal
Unmerge
root #
emerge --ask --depclean --verbose gui-wm/hyprland gui-libs/xdg-desktop-portal-hyprland
See also
- Hyprpaper — a blazing fast Wayland wallpaper utility with IPC controls.
- List of software for Wayland — various desktop related packages for Wayland
External resources
- wlroots — A modular Wayland compositor library
- Introduction to wlroots