From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

hyprland is an open-source Wayland compositor written in C++.


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:

user $man hyprland

Also the hyprland wiki is an excellent documentation.


Each user running hyprland can edit the default configuration file in order to run a customized session. The path of the file should be the default location ~/.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

Monitor can be adjusted by modifying ~/.config/hypr/hyprland.conf. Once the file is saved, the configuration will be 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

Check out hyprland wiki monitor 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 the 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 the 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 the 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 the 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


Package app-misc/brightnessctl which is available in the GURU can be used to adjust backlights and brightness.

root #emerge --ask app-misc/brightnessctl

Here is an example config:

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

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 the keyboard shortcuts for screen brightness support
bind = , XF86AudioPlay, exec, playerctl play-pause
bind = , XF86AudioNext, exec, playerctl next
bind = , XF86AudioPrev, exec, playerctl previous
bind = , XF86audiostop, exec, playerctl stop

Terminal emulator

The Gentoo Wiki lists terminal emulators that support Wayland 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.

Status bars


gui-apps/waybar can be used as a highly customizable status bar. It requires some extra configuration and patches for hyprland.

root #emerge --ask gui-apps/waybar

Use flags

Compile waybar with USE=experimental to make the wlr/workspaces widget work.

Switching workspaces by clicking

Put this is patch into /etc/portage/patches/gui-apps/waybar/hyprland-clickable-workspaces.patch, then re-emerge gui-apps/waybar.

It makes waybars workspaces switcher use hyprctl.

FILE /etc/portage/patches/gui-apps/waybar/hyprland-clickable-workspaces.patch
--- a/src/modules/wlr/workspace_manager.cpp
+++ b/src/modules/wlr/workspace_manager.cpp
@@ -511,7 +511,8 @@ auto Workspace::handle_clicked(GdkEventButton *bt) -> bool {
   if (action.empty())
     return true;
   else if (action == "activate") {
-    zext_workspace_handle_v1_activate(workspace_handle_);
+    const std::string command = "hyprctl dispatch workspace " + name_;
+	system(command.c_str());
   } else if (action == "close") {
   } else {

Persistent workspaces

A patch for persistent workspaces was recently merged in Waybars Github repository, but it is not available yet in the current versioned package on Gentoo. Emerge waybar as live ebuild (9999) to get this feature.

Other status bars

See Wayland Desktop Landscape.

Screen Sharing

See hyprland screensharing

XDPH is not necessary. Hyprland will work with XDPW, but XDPH has more features, like e.g. window sharing. XDPH will work on other wlroots-based compositors, although limited to the XDPW features (other will be disabled).


xdg-desktop-portals are helper programs for desktop environments. The 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 in hyprland on if screensharing does not work, a problem with the xdg-desktop-portal is likely the reason. Hyprland does work with the gui-libs/xdg-desktop-portal-wlr, but screensharing will not work with this. Hyprland upstream forked xdg-desktop-portal-wlr into gui-libs/xdg-desktop-portal-hyprland (available in the GURU),

root #emerge --ask gui-libs/xdg-desktop-portal-hyprland
Currently, gui-libs/xdg-desktop-portal-hyprland is masked as it depends on Qt6, which is also masked. See bug #838970.

xdg-desktop-portal-hyprland needs to be started after Hyprland starts. This is done the easiest using hyprland's exec-once function. It is also a good idea to tell D-BUS, that the current desktop is Hyprland To do so, this should be added in the Hyprland config:

FILE ~/.config/hypr/hyprland.confXDPH environment variables
env = XDG_SESSION_TYPE, wayland
exec-once = wl-clipboard-history -t
exec-once = dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP

OpenRC users should not worry to much about the --systemd flag here. The command will update the systemd --user environment if possible, so it will simply not do that on OpenRC.

Also a script should be executed at start. This script will start the 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
/usr/libexec/xdg-desktop-portal-hyprland &
sleep 2
/usr/lib/xdg-desktop-portal &

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 have some lacking functionality (like besaid screensharing).

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.

Executing Hyprland

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.

Launching Hyprland with TTY login

This is a simple method to start Hyprland, this can be added to a user's shell rc file, and once logged in, a Hyprland session will execute.

FILE ~/.bashrcLaunch Hyprland after logging into the first TTY
if [ -z "${WAYLAND_DISPLAY}" ] && [ "${XDG_VTNR}" -eq 1 ]; then
    dbus-run-session Hyprland