Hyprland

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

Installation

Emerge

With the fast pace of Hyprland releases, and the dependencies that are required, use of the hyproverlay repository is recommended.

To add the hyproverlay overlay, run:

As third party repositories don't have the "stable" keyword, use the following to accept all packages in the overlay, to avoid having to add packages one by one:

*/*::hyproverlay

More information on this topic can be found at /etc/portage/package.accept_keywords.

Configuration

To view all available configuration options, run:

or visit the Hyprland wiki link in this page's InfoBox.

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:

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.

monitor = , preferred, auto, 1

monitor = eDP-1, 2560x1440@165.003006, 0x0, 1

monitor = eDP-1, 2560x1440@165.003006, 0x0, 1, transform, 1

Refer to the "Monitors" page on the Hyprland wiki for more information.

Sound volume

If PulseAudio is being used, the following configuration can be used for changing sound volume:

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

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

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

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

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::GURU is available in GURU and can be used to adjust backlights and brightness.

Here is an example config for monitor backlight control:

bind = , XF86MonBrightnessDown, exec, brightnessctl set 5%-
bind = , XF86MonBrightnessUp, exec, brightnessctl set 5%+

Here is an example config for keyboard backlight control:

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.

Here is an example config:

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 List of software for Wayland 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

Some display managers may work. Without a display manager, Hyprland can be started from a tty:

On login with tty

A simple function can be added to a user's shell profile file to execute a Hyprland session upon login, which will only be evaluated in login shells:

dbus-run-session start-hyprland

If using Zsh, this function can be put it in ~/.zprofile.

Status bars

Refer to the "List of software for Wayland" page 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:

gui-apps/hyprshot ~amd64

Then emerge:

and add the following to 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

Refer to the "hyprland Screen sharing" page on the Hyprland wiki.

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

xdg-desktop-portal-hyprland needs to be started after Hyprland starts. This is best done with Hyprland's exec-once function. It's also a good idea to tell D-Bus that the current desktop is Hyprland. To do so, add this to the Hyprland config file:

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.

If not using systemd, a script should be used to start xdg-desktop-portal-hyprland. Although the script can reside anywhere, for this example, it will be located at ~/.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'

Once that file has been created, add the following to the hyprland.conf file:

exec-once = ~/.config/hypr/xdg-portal-hyprland

This will ensure that no other desktop portal is running while using Hyprland, which can cause problems.

xdg-desktop-portal-gnome

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:

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.

Portage's package.provided feature can 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 that Flatpak applications can send notifications, it's not enough to simply install the gui-libs/xdg-desktop-portal-hyprland package, a fork of gui-libs/xdg-desktop-portal-wlr claiming to support screencast and screenshot functionalities.

For more context, refer to xdg-desktop-portal-wlr issue #42, which shows that the sys-apps/xdg-desktop-portal-gtk package needs to both be installed and started with Hyprland.

If ~/.config/hypr/xdg-portal-hyprland was added, modify it as follows:

#!/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 the case when trying to mount filesystems and drives through the use of a graphical file manager. Along 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, which can be installed from the GURU repository:

Hyprpolkitagent can be autostarted by adding the following line to hyprland.conf:

exec-

Removal

Unmerge

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:

exec = start-pulseaudio-x11

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. It is recommended to install a system tray, such as Waybar with the tray USE flag.

See also

• Hyprpaper — a blazing fast Wayland wallpaper utility with IPC controls.
• List of software for Wayland — various desktop related packages for Wayland

References