From Gentoo Wiki
Jump to:navigation Jump to:search

hyprland is an open-source wlroots-based Wayland compositor written in C++. The rendering backend is GLES 3.2.[1]


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


root #emerge --ask gui-wm/hyprland


To view all available configuration options, run:

user $man Hyprland

or visit the Hyprland wiki link above.


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
Monitor eDP-1 (ID 0):
	2560x1440@165.003006 at 0x0
	description: Chimei Innolux Corporation 0x152A (eDP-1)
	make: Chimei Innolux Corporation
	model: 0x152A
	active workspace: 1 (1)
	reserved: 0 35 0 0
	scale: 1.00
	transform: 0
	focused: yes
	dpmsStatus: 1
	vrr: 0

Monitors can be adjusted by modifying ~/.config/hypr/hyprland.conf. Once the file is saved, the configuration is reloaded automatically.

FILE ~/.config/hypr/hyprland.confauto configuration of monitors
monitor = , preferred, auto, 1
FILE ~/.config/hypr/hyprland.confConfigure primary display which is centered
monitor = eDP-1, 2560x1440@165.003006, 0x0, 1
FILE ~/.config/hypr/hyprland.confConfigure alternate display which is vertical
monitor = 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:

FILE ~/.config/hypr/hyprland.confSet keyboard shortcuts to change sound volume for pulseaudio
bind = , 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):

FILE ~/.config/hypr/hyprland.confSet keyboard shortcuts to change sound volume for PipeWire
bind = , 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:

FILE ~/.config/hypr/hyprland.confSet keyboard shortcuts to change sound volume for ALSA
bind = , 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:

FILE ~/.config/hypr/hyprland.confSet keyboard shortcuts to change sound volume for sndio
bind = , XF86AudioRaiseVolume, exec, sndioctl -f snd/default output.level=+0.05
bind = , XF86AudioLowerVolume, exec, sndioctl -f snd/default output.level=-0.05

Other special hotkeys

FILE ~/.config/hypr/hyprland.confSet the keyboard shortcuts for muting mic and sound volume for pulseaudio
bind = , 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:

FILE ~/.config/hypr/hyprland.confSet keyboard shortcuts for screen brightness support
bind = , XF86MonBrightnessDown, exec, brightnessctl set 5%-
bind = , XF86MonBrightnessUp, exec, brightnessctl set 5%+

Here is an example config for keyboard backlight control:

FILE ~/.config/hypr/hyprland.confSet keyboard shortcuts for keyboard brightness support
bind = , 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.


media-sound/playerctl can be used to control multimedia apps.

root #emerge --ask media-sound/playerctl

Here is an example config:

FILE ~/.config/hypr/hyprland.confSet keyboard shortcuts for media playback
bind = , 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.

FILE ~/.bash_profileLaunch Hyprland after logging into a TTY
dbus-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

See hyprland screensharing

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-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:

FILE ~/.config/hypr/hyprland.confXDPH environment variables
env = XDG_SESSION_TYPE, wayland
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.

FILE ~/.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

FILE ~/.config/hypr/xdg-portal-hyprland
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.


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 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:

FILE ~/.config/hypr/xdg-portal-hyprland
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 amdgpu-pro-vulkan to, 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



root #emerge --ask --depclean --verbose gui-wm/hyprland gui-libs/xdg-desktop-portal-hyprland

See also

External resources