Hyprland

This wiki page is about Hyprland, a wayland based tiling compositor with all the eyecandy, powerful plugins and much more.

Refer to hyprland Tutorial to get started on using Hyprland.

Prerequisites

• Internet connectivity, unless the packages have been pre-fetched into a local cache.
• Install appropriate Graphics driver drivers for your hardware. Without graphics drivers, errors are likely to occur when starting your desktop.
• A non-root user account.
• The community repository must be enabled.
• Set up eudev.
• Install and enable D-Bus. Without D-Bus, icons and keyboard shortcuts may be missing.
• Install wayland-base.This enables elogind as seat manager, enables community repository and enables eudev.

Installation

To run the hyprland nicely, it is likely that you will need at least those packages:

# apk add hyprland hyprland-plugin-manager hyprland-protocols \ hyprland-wallpapers wayland xwayland elogind elogind-openrc \ polkit-elogind polkit-openrc openrc-user-pam eudev \ eudev-openrc dbus dbus-openrc dbus-daemon-launch-helper pipewire \ pipewire-openrc pipewire-pulse pipewire-pulse-openrc \ wireplumber wireplumber-openrc

Optionally

# apk add waybar hyprland-wallpapers \ hyprutils hyprcursor wlroots grim slurp \ wofi kitty dolphin

Obviously there are other choices: `rofi`, `alacritty`, etc...

Setup

As a bare minimum:

#setup-wayland-base

openrc comes with "user services" so we can use it to start required services when you login.

1) add user to seat group - required for elogind

2) add user to audio, video, pipewire, input groups

3) create a symbolic link for user service

# /etc/init.d/user.$YOUR_USERNAME_HERE -> /etc/init.d/user

4) enable linger for your user

# loginctl enable-linger $YOUR_USERNAME_HERE

5) Add required services to your user services

$ ls -la /etc/user/init.d/

$ rc-status --user

$ for service in dbus wireplumber pipewire pipewire-pulse; do rc-update --user add "$service" && rc-service --user "$service" start; done

Configuration

The default config is in

/usr/share/hypr/hyprland.conf

and based on that you may want to customize yours

~/.config/hypr/hyprland.conf

consistent icon theme

Depending on what applications you are running, you only need the HYPRCURSOR_THEME environment, it should work for all modern applications. But since you are reading this, you probably found an incompatible application. You have the option to disable hyprcursors, then you need only one theme. Otherwise you need to download a theme that is available as hyprcursors and xcursors (e.g. rose-pine-hyprcursor).

Contents of ~/.config/hypr/hyprland.conf

# Set the theme for most applications env = HYPRCURSOR_THEME,$your_hyprcursor_theme env = HYPRCURSOR_SIZE,24 # Set the theme for some Qt applications env = XCURSOR_THEME,$your_xcursor_theme env = XCURSOR_SIZE,24 # Set the theme for some GTK applications exec-once = gsettings set org.gnome.desktop.interface cursor-theme $your_xcursor_theme exec-once = gsettings set org.gnome.desktop.interface cursor-size 24

If you use gsettings make sure you have installed gsettings-desktop-schemas package.

Plugins

hyprland-plugin-manager

From Alpine v3.22 on the hyprland-plugin-manager package is available. It installs the complete development-tree of hyprland, since it requires to compile hyprland. It is possible to uninstall hyprland-plugin-manager after the plugin is compiled.

hyrpland-plugins

From Alpine v3.23 (not yet released) on or on edge it is possible to install the official plugins as a package. Checkout the subpackages to install individual plugins.

loading plugins

Contents of ~/.config/hypr/hyprland.conf

plugin = /usr/lib/libhyprexpo.so plugin { hyprexpo { columns = 3 gap_size = 0 workspace_method = first 1 } }

This is also useful if you have uninstalled hyprland-plugin-manager and you can't load the plugin via it.

Troubleshooting

Black/Magenta checkerboard background: Hyprland failed to load 1 essential asset

As of Hyprland 0.45.0, upstream shows a scary message (and an ugly graphic) if you don't have their wallpapers installed.

The ugly graphic goes away when you've launched a wallpaper utility, but the scary message remains.

The canonical way to solve this is to install hyprland-wallpapers package using the command:

# apk add hyprland-wallpapers

Or you can just have some file at /usr/share/hypr/wall0.png or /usr/local/share/hypr/wall0.png and modify your config file to have a line as follows:

Contents of ~/.config/hypr/hyprland.conf

misc { force_default_wallpaper = 0 }

Hyprland crashes almost immediately

Hyprland 0.46 has a bug where the default configuration will crash if Xwayland is not installed. You can either install xwayland, or disable in your config:

Contents of ~/.config/hypr/hyprland.conf

xwayland:enabled = false

This should be fixed in the next update.

warning message about hyprland-qtutils

Hyprland 0.46 and newer suggest you install hyprland-qtutils, which is currently not available in alpine.

Your system does not have hyprland-qtutils installed. This is a runtime dependency for some dialogs. Consider installing it.

You can disable the check in your config like so:

Contents of ~/.config/hypr/hyprland.conf

misc:disable_hyprland_qtutils_check = true

DBUS_SESSION_BUS_ADDRESS unset

If you're using login manager, create a copy of /usr/share/wayland-sessions/hyprland.desktop that starts Hyprland within D-Bus session:

Exec=dbus-run-session -- Hyprland

Also make sure that D-Bus is started as a system service.

See Also

• Official Hyprland wiki