Hyprland

Resources

hyprland is an open-source 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

Data provided by the Gentoo Package Database · Last update: 2024-12-10 15:21 More information about USE flags

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

Monitor eDP-1 (ID 0):
	2560x1440@165.003006 at 0x0
	description: Chimei Innolux Corporation 0x152A (eDP-1)
	make: Chimei Innolux Corporation
	model: 0x152A
	serial: 
	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.

Playerctl

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

Note
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

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.

Screenshotting

While there are a few options to screenshot in Hyprland, there is an official tool, hyprshot

First, unmask hyprshot:

FILE /etc/portage/package.accept_keywords/hyprshot

gui-apps/hyprshot ~amd64

Then, emerge hyprshot:

root #emerge --ask gui-apps/hyprshot

add the following to hyprland.conf:

FILE ~/.config/hypr/hyprland.conf

# Screenshot a window
bind = $mainMod, PRINT, exec, hyprshot -m window
# Screenshot a monitor
bind = , PRINT, exec, hyprshot -m output
# Screenshot a region
bind = $mainMod SHIFT, PRINT, exec, hyprshot -m region

Screen sharing

See hyprland screensharing

Note
XDPH is not necessary. Hyprland will work with XDPW, but XDPH has more features, like window sharing. XDPH will work on 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:

FILE ~/.config/hypr/hyprland.confXDPH environment variables

env = 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.

Note
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

#!/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

Important
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.

Note
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

#!/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'

Polkit Authentication

In order for processes/apps which do not have privilege to communicate with more privileged processes/apps, unprivileged processes will need the sys-auth/polkit package. For example, this is used when trying to mount filesystems and drives through the use of a graphical file manager. Alongside with polkit (PolicyKit), the user will need a "polkit agent", which is used to make the user of a session prove that they really are the user or an administrative user. The Hyprland Wiki recommends "hyprpolkitagent", but unfortunately, it is not available in either the main Gentoo ebuild repository or the user-maintained GURU repository. So, the best option is to use another polkit agent.

In this example, Hyprland will be using KDE'S polkit agent, since it is even mentioned on the Hyprland Wiki; kde-plasma/polkit-kde-agent Once installed, the user will have to add this to their ~/.config/hypr/hyprland.conf:

FILE ~/.config/hypr/hyprland.confEnabling KDE polkit agent

exec-once = /usr/libexec/polkit-kde-authentication-agent-1

Removal

Unmerge

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

Troubleshooting

No Sound on OBS

Pulseaudio may fail to autostart, and OBS will fail to connect to the pulseaudio server. Add the following in hyprland.conf, after dbus:

FILE ~/.config/hypr/hyprland.conf

exec = start-pulseaudio-x11

Waybar Crashes When Turning On an HDMI Monitor

This bug has been fixed in 0.44 of Hyprland. To switch to this newer version, you will need to unmask hyprland and its dependencies, as well as switch to GCC 14.

First, edit your package.accept_keywords:

FILE /etc/portage/package.use/hyprland

gui-wm/hyprland ~amd64
gui-libs/aquamarine ~amd64
dev-libs/hyprland-protocols ~amd64
gui-libs/hyprutils ~amd64
sys-devel/gcc ~amd64

Emerge GCC:

root #emerge --ask sys-devel/gcc

Switch to GCC 14 with eselect:

user $eselect gcc list

[1] x86_64-pc-linux-gnu-13 *
[2] x86_64-pc-linux-gnu-14

Below will be listed your installed GCC packages. Find the one for 14 and set it:

root #eselect gcc set 2

Relaunch your terminal (or update your environment) and emerge hyprland:

root #emerge --ask gui-wm/hyprland

Steam cannot re-open without a tray

Running steam, either from terminal or an application launcher, can only be done once. After closing steam, it will run in the background and expect a tray. To re-open it, it is recommended you install a system tray. You can install waybar with the tray USE flag to accomplish this.

References

↑ https://photon-reddit.com/r/hyprland/comments/141g6b2/what_is_the_default_render_backend_of_hyprland/

[1] ttps://photon-reddit.com/r/hyprland/comments/141g6b2/what_is_the_default_render_backend_of_hyprland/

[1]

Hyprland

Contents

Installation

USE flags

USE flags for gui-wm/hyprland A dynamic tiling Wayland compositor that doesn't sacrifice on its looks

Emerge

Configuration

Files

Display configuration

Sound volume

Other special hotkeys

Monitor and keyboard backlights

Playerctl

Terminal emulator

Executing Hyprland

On login with tty

Status bars

Screenshotting

Screen sharing

xdg-desktop-portal-hyprland

xdg-desktop-portal-gnome

Flatpak portals

xdg-desktop-portals

Polkit Authentication

Removal

Unmerge

Troubleshooting

No Sound on OBS

Waybar Crashes When Turning On an HDMI Monitor

Steam cannot re-open without a tray

See also

References