Alpine Linux - User contributions [en]

Bootloaders

2025-09-13T12:47:18Z

Vegas:

A ''bootloader'' is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a ''boot manager''. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.

The following bootloaders are available in Alpine Linux:-

* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux. 
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems. 
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader. 
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader. 
* [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.

A [[#Using a UKI|Unified Kernel Image (UKI)]] is additionally supported, available for UEFI only. It is a UEFI executable that can be useful in [https://uapi-group.org/specifications/specs/unified_kernel_image/ certain use cases], including secure boot, clouds and containers.

== Syslinux ==

If you want to switch from another bootloader back to ''Syslinux'', or if for some reason you want to install Syslinux manually, then the following steps are required.

Install the {{pkg|syslinux}} package:

{{cmd|# apk add syslinux}}

If you're using GPT partitions, then install the ''GPT MBR'' onto the drive that you want to install the bootloader on (in this case, {{path|/dev/sda}}):

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}

Or, if you're using DOS partitions, then install the ''DOS MBR'' instead:

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}


Next, install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS and UFS/FFS filesystems.

{{cmd|# extlinux --install /boot}}

The configuration file is located in {{path|/boot/extlinux.conf}}.

Alpine Linux ships with a script, <code>update-extlinux</code>, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.

You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory e.g. for dual booting.

=== Using EFI with syslinux ===

The Alpine Linux installer automatically uses [[#GRUB|GRUB]] if EFI mode is detected. The section below is specifically about using EFI with Syslinux:

Assuming that {{path|/mnt}} is a FAT32 partition of type EF00 and that {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:

{{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
# cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
# cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
# cp /boot/vmlinuz* /mnt/EFI/syslinux/
# cp /boot/initramfs* /mnt/EFI/syslinux/
</nowiki>}}

You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).

In the end, the {{path|/mnt/EFI/syslinux/syslinux.cfg}} file should look like this:

{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
DEFAULT menu.c32
PROMPT 0
MENU TITLE Alpine/Linux Boot Menu
MENU HIDDEN
MENU AUTOBOOT Alpine will be booted automatically in # seconds
TIMEOUT 10
LABEL lts
MENU DEFAULT
MENU LABEL Linux lts
LINUX /vmlinuz-lts
INITRD /initrd-lts
APPEND root=/dev/sda3 modules=sd-load,usb-storage,ext4 quiet
</nowiki>}}

Finally, add <code>syslinux</code> to the EFI boot menu. Assuming that {{path|/dev/sda}} is your hard drive —'''''be careful to check first what is its path on your device and to adjust accordingly''''':

{{cmd|<nowiki># apk add efibootmgr
# efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
</nowiki>}}

You can now verify that the boot entry has been added:

'''efibootmgr'''
<pre>
BootCurrent: 0001
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
</pre>

== rEFInd ==
{{Main|rEFInd}}

[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.

== GRUB ==

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}

For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI-compatible filesystem, such as FAT32.

{{cmd|# apk add grub-efi efibootmgr}}

Next, install the MBR and GRUB binaries to disk for BIOS mode:

{{cmd|# grub-install /dev/vda}}

For EFI mode:

{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}

Then, add this line to {{path|/etc/default/grub}}:

{{cat|/etc/default/grub|<nowiki># GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"</nowiki>}}

GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:

{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

This script can be configured via the {{path|/etc/default/grub}} file.

If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].

Consult [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html gnu.org's online manual] for a list of available <code>grub-mkconfig</code> configuration options.

== EFI Boot Stub ==

To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with ''efibootmgr''.

=== efibootmgr ===

Install {{Pkg|efibootmgr}}:
{{cmd|# apk add efibootmgr}}

Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.

{{cat|add-bootentry|<nowiki>#!/bin/sh

params="root=/dev/sdXZ rootfstype=ext4 rw \
initrd=\intel-ucode.img \
initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
--disk /dev/sdX --part Y \
--loader /vmlinuz-lts \
--unicode "${params}" \
--verbose
</nowiki>}}

Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-edge}}, then replace <code>lts</code> with <code>edge</code> in the script.

{{Tip|If you're modifying EFI records from a running system (e. g. migrating from GRUB), you can populate {{ic|$params}} from {{ic|/proc/cmdline}}. Make sure to append {{ic|initrd}} param if it's missing since GRUB does not add it to the command line.}}

{{Note| The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
}}

Optionally, set the newly-created entry as the default:

{{cmd|# efibootmgr -n XXXX}}

Where <code>XXXX</code> is the boot number of the new entry.

{{Note| The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update <code>fstab</code> to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}. }}

== Using a UKI ==

'''[https://github.com/uapi-group/specifications/blob/main/specs/unified_kernel_image.md#unified-kernel-image-uki Unified Kernel Image]''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.

The [[UEFI Secure Boot]] page contains the instructions for setting up an a UKI. While this is typically done in order to ''SecureBoot'', it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.

Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}} :

{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the edge kernel, install the UKI into the default UEFI path.
if [ "$1" == "edge" ]; then
output_dir="/efi/EFI/Boot/"
output_name="bootx64.efi"
fi
</nowiki>}}

{{Note| {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures, the exact name will vary.}}

== See also ==
* [[Enable Serial Console on Boot]]
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki]
* [https://www.denx.de/wiki/U-Boot/ReleaseCycle U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

Bootloaders

2025-09-13T12:46:32Z

Vegas:

A ''bootloader'' is a computer program that is responsible for booting a computer. In the case where it also provides an interactive menu with multiple boot choices, then it's often called a ''boot manager''. This page shows the basic steps that you need to perform if, for any reason, you want to switch bootloaders or to apply some manual configuration.

The following bootloaders are available in Alpine Linux:-

* <code>[[#Syslinux|Syslinux]]</code> is the default lightweight bootloader used in Alpine Linux. 
* <code>[[#rEFInd|rEFInd]]</code> is an easy-to-use ''EFI'' boot menu that allows booting different operating systems. 
* <code>[[#GRUB|GRUB]]</code> is a standard Linux bootloader. 
* <code>[[#EFI_Boot_Stub|EFI Boot Stub]]</code> allows for booting Linux directly from a motherboard supporting ''UEFI'' or from another bootloader. 
* [[UEFI Secure Boot]] uses {{pkg|systemd-efistub}} or {{pkg|stubbyboot-efistub}}.

A [[#Using a UKI|Unified Kernel Image (UKI)]] is additionally supported, available for UEFI only. It is a UEFI executable that can be useful in [https://uapi-group.org/specifications/specs/unified_kernel_image/ certain use cases], including secure boot, clouds and containers.

== Syslinux ==

If you want to switch from another bootloader back to ''Syslinux'', or if for some reason you want to install Syslinux manually, then the following steps are required.

Install the {{pkg|syslinux}} package:

{{cmd|# apk add syslinux}}

If you're using GPT partitions, then install the ''GPT MBR'' onto the drive that you want to install the bootloader on (in this case, {{path|/dev/sda}}):

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/gptmbr.bin of=/dev/sda</nowiki>}}

Or, if you're using DOS partitions, then install the ''DOS MBR'' instead:

{{cmd|<nowiki># dd bs=440 count=1 conv=notrunc if=/usr/share/syslinux/mbr.bin of=/dev/sda</nowiki>}}


Next, install the required Syslinux binaries. Despite being called <code>extlinux</code>, Syslinux supports booting from FAT12/16/32, NTFS, ext2/3/4, [[Btrfs|btrfs]], XFS and UFS/FFS filesystems.

{{cmd|# extlinux --install /boot}}

The configuration file is located in {{path|/boot/extlinux.conf}}.

Alpine Linux ships with a script, <code>update-extlinux</code>, that automatically (re)generates this file, for example, on updates to Syslinux. The settings for this script can be found in {{path|/etc/update-extlinux.conf}}, including the option to disable automatic overwriting of {{path|/boot/extlinux.conf}}.

You can also place additional menu entries in the {{path|/etc/update-extlinux.d/}} directory e.g. for dual booting.

=== Using EFI with syslinux ===

The Alpine Linux installer automatically uses [[#GRUB|GRUB]] if EFI mode is detected. The section below is specifically about using EFI with Syslinux:

Assuming that {{path|/mnt}} is a FAT32 partition of type EF00 and that {{path|/boot}} belongs to the rootfs created after running <code>setup-disk</code>:

{{cmd|<nowiki># mkdir -p /mnt/EFI/syslinux
# cp /usr/share/syslinux/efi64/* /mnt/EFI/syslinux/
# cp /boot/extlinux.conf /mnt/EFI/syslinux/syslinux.cfg
# cp /boot/vmlinuz* /mnt/EFI/syslinux/
# cp /boot/initramfs* /mnt/EFI/syslinux/
</nowiki>}}

You may need to modify {{path|/mnt/EFI/syslinux/syslinux.cfg}} to change the paths to absolute paths (just add a / in front of the vmlinuz/initramfs entries), or copy the files to {{path|/mnt/EFI/syslinux}} instead (XXX: untested).

In the end, the {{path|/mnt/EFI/syslinux/syslinux.cfg}} file should look like this:

{{cat|/mnt/EFI/syslinux/syslinux.cfg|<nowiki>...
DEFAULT menu.c32
PROMPT 0
MENU TITLE Alpine/Linux Boot Menu
MENU HIDDEN
MENU AUTOBOOT Alpine will be booted automatically in # seconds
TIMEOUT 10
LABEL lts
MENU DEFAULT
MENU LABEL Linux lts
LINUX /vmlinuz-lts
INITRD /initrd-lts
APPEND root=/dev/sda3 modules=sd-load,usb-storage,ext4 quiet
</nowiki>}}

Finally, add <code>syslinux</code> to the EFI boot menu. Assuming that {{path|/dev/sda}} is your hard drive —'''''be careful to check first what is its path on your device and to adjust accordingly''''':

{{cmd|<nowiki># apk add efibootmgr
# efibootmgr -c -d /dev/sda -p 1 -l \\EFI\\syslinux\\syslinux.efi -L "ALPINE-SYSLINUX"
</nowiki>}}

You can now verify that the boot entry has been added:

'''efibootmgr'''
<pre>
BootCurrent: 0001
Timeout: 0 seconds
BootOrder: 0001,0000,0002,...
Boot001* ALPINE-SYSLINUX HD(1,GPT,xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)/FILE(\EFI\syslinux\syslinux.efi)
</pre>

== rEFInd ==
{{Main|rEFInd}}

[[rEFInd]] provides a graphical boot menu for [[UEFI]] systems.

== GRUB ==

To install GRUB in BIOS mode, (optionally) remove the Syslinux package and install the required GRUB packages:

{{cmd|<nowiki># apk del syslinux
# apk add grub grub-bios
</nowiki>}}

For EFI, install GRUB's EFI package instead. Note that {{path|/boot}} has to be an EFI-compatible filesystem, such as FAT32.

{{cmd|# apk add grub-efi efibootmgr}}

Next, install the MBR and GRUB binaries to disk for BIOS mode:

{{cmd|# grub-install /dev/vda}}

For EFI mode:

{{cmd|<nowiki># grub-install --target=x86_64-efi --efi-directory=/boot</nowiki>}}

Then, add this line to {{path|/etc/default/grub}}:

{{cat|/etc/default/grub|<nowiki># GRUB_CMDLINE_LINUX_DEFAULT="quiet rootfstype=ext4 modules=sd-mod,usb-storage,ext4"</nowiki>}}

GRUB ships with an automatic configuration generator, including some automatic detection of other operating systems installed on the device:

{{cmd|# grub-mkconfig -o /boot/grub/grub.cfg}}

This script can be configured via the {{path|/etc/default/grub}} file.

If the font in the GRUB boot screen appears too small, then [[Fonts#Changing_GRUB_font_and_font_size|change the GRUB font]].

Consult [https://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html gnu.org's online manual] for a list of available <code>grub-mkconfig</code> configuration options.

== EFI Boot Stub ==

To boot directly from your motherboard's UEFI boot menu, a boot entry needs to be created either with a UEFI shell or with ''efibootmgr''.

=== efibootmgr ===

Install {{Pkg|efibootmgr}}:
{{cmd|# apk add efibootmgr}}

Create a boot entry. It is recommended to do this in a script, as efibootmgr does not allow for editing entries.

{{cat|add-bootentry|<nowiki>#!/bin/sh

params="root=/dev/sdXZ rootfstype=ext4 rw \
initrd=\intel-ucode.img \
initrd=\initramfs-lts"

efibootmgr --create --label "Alpine Linux" \
--disk /dev/sdX --part Y \
--loader /vmlinuz-lts \
--unicode "${params}" \
--verbose
</nowiki>}}

Where {{path|/dev/sdXY}} contains the EFI partition and {{path|/dev/sdXZ}} contains the root partition. If you are using {{Pkg|linux-edge}}, then replace <code>lts</code> with <code>edge</code> in the script.

{{Tip|If you're modifying EFI records from a running system (e. g. migrating from GRUB), you can use {{ic|cat /proc/cmdline}} to get current kernel params. Make sure to add {{ic|initrd}} param if it's missing since GRUB does not add it to the command line.}}

{{Note| The kernel contains the [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/init/do_mounts.c#n254 exhaustive list] of ways to specify the block device. For a more robust boot entry, it is recommended to use a persistent name such as the PARTUUID.
}}

Optionally, set the newly-created entry as the default:

{{cmd|# efibootmgr -n XXXX}}

Where <code>XXXX</code> is the boot number of the new entry.

{{Note| The loader and initrd file arguments are relative to the EFI partition. In a default installation, Alpine Linux places these files in {{path|/boot/}}, while EFI is mounted to {{path|/boot/efi/}}. You can either update <code>fstab</code> to mount EFI at {{path|/boot/}}, or manually copy them to {{path|/boot/efi/}}. }}

== Using a UKI ==

'''[https://github.com/uapi-group/specifications/blob/main/specs/unified_kernel_image.md#unified-kernel-image-uki Unified Kernel Image]''' (UKI) is supported in UEFI only. It is possible to boot directly into a UKI. A UKI is a single file that contains the initfs, kernel and cmdline.

The [[UEFI Secure Boot]] page contains the instructions for setting up an a UKI. While this is typically done in order to ''SecureBoot'', it is perfectly feasible to skip enrolling the custom keys and to leave SecureBoot off.

Additionally, it is possible to install the UKI in the default fallback path used by most UEFI implementations. By installing the UKI into this path, the system will automatically boot into it if no other entries are defined. This can be automated as part of the kernel hook by adding the following to {{path|/etc/kernel-hooks.d/secureboot.conf}} :

{{cat|/etc/kernel-hooks.d/secureboot.conf|<nowiki># For the edge kernel, install the UKI into the default UEFI path.
if [ "$1" == "edge" ]; then
output_dir="/efi/EFI/Boot/"
output_name="bootx64.efi"
fi
</nowiki>}}

{{Note| {{path|bootx64.efi}} is only correct for <code>x86_64</code> systems. For other architectures, the exact name will vary.}}

== See also ==
* [[Enable Serial Console on Boot]]
* [https://wiki.gentoo.org/wiki/Bootloader Gentoo Wiki]
* [https://wiki.archlinux.org/title/Arch_boot_process#Boot_loader Archwiki]
* [https://wiki.postmarketos.org/wiki/Category:Bootloaders PostmarketOS Wiki]
* [https://www.denx.de/wiki/U-Boot/ReleaseCycle U-Boot Release Cycle]

[[Category:Installation]]
[[Category:Booting]]

Hyprland

2025-09-13T12:39:06Z

Vegas:

This wiki page is about [https://hyprland.org Hyprland], a [[wayland]] based tiling compositor with all the eyecandy, powerful plugins and much more.

Refer to [https://wiki.hyprland.org/Getting-Started/Master-Tutorial/ hyprland Tutorial] to get started on using Hyprland.

== Prerequisites ==
{{:Include:Desktop prerequisites}}
* Install [[Alpine_setup_scripts#setup-wayland-base|wayland-base]].This enables [[elogind]] as [[Seat manager|seat manager]], enables [[Repositories#Community|community repository]] and enables [[eudev]].

== Installation ==

Install the package {{Pkg|hyprland|arch=}} using the command: {{Cmd|# apk add hyprland}}

== Configuration ==

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

{{Cat|~/.config/hypr/hyprland.conf|<nowiki># 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</nowiki>}}

If you use gsettings make sure you have installed {{pkg|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 [https://github.com/hyprwm/hyprland-plugins official plugins] as a [https://pkgs.alpinelinux.org/package/edge/community/x86_64/hyprland-plugins package]. Checkout the subpackages to install individual plugins.

=== loading plugins ===

{{Cat|~/.config/hypr/hyprland.conf|<nowiki>plugin = /usr/lib/libhyprexpo.so
plugin {
hyprexpo {
columns = 3
gap_size = 0
workspace_method = first 1
}
}
</nowiki>}}

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 [https://wiki.hyprland.org/Useful-Utilities/Wallpapers/ wallpaper utility], but the scary message remains.

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

{{Cmd|# apk add hyprland-wallpapers}}

Or you can just have some file at {{Path|/usr/share/hypr/wall0.png}} or {{Path|/usr/local/share/hypr/wall0.png}} and modify your config file to have a line as follows: {{Cat|~/.config/hypr/hyprland.conf|<nowiki>misc {
force_default_wallpaper = 0
}</nowiki>}}

=== 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 {{pkg|xwayland}}, or disable in your config:

{{Cat|~/.config/hypr/hyprland.conf|<nowiki>xwayland:enabled = false</nowiki>}}

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.

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

You can disable the check in your config like so:

{{Cat|~/.config/hypr/hyprland.conf|<nowiki>misc:disable_hyprland_qtutils_check = true</nowiki>}}

=== DBUS_SESSION_BUS_ADDRESS unset ===

If you're using login manager, create a copy of {{ic|/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 ==

* [https://wiki.hyprland.org Official Hyprland wiki]

[[Category:compositor]]

Hyprland

2025-09-13T12:38:18Z

Vegas:

This wiki page is about [https://hyprland.org Hyprland], a [[wayland]] based tiling compositor with all the eyecandy, powerful plugins and much more.

Refer to [https://wiki.hyprland.org/Getting-Started/Master-Tutorial/ hyprland Tutorial] to get started on using Hyprland.

== Prerequisites ==
{{:Include:Desktop prerequisites}}
* Install [[Alpine_setup_scripts#setup-wayland-base|wayland-base]].This enables [[elogind]] as [[Seat manager|seat manager]], enables [[Repositories#Community|community repository]] and enables [[eudev]].

== Installation ==

Install the package {{Pkg|hyprland|arch=}} using the command: {{Cmd|# apk add hyprland}}

== Configuration ==

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

{{Cat|~/.config/hypr/hyprland.conf|<nowiki># 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</nowiki>}}

If you use gsettings make sure you have installed {{pkg|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 [https://github.com/hyprwm/hyprland-plugins official plugins] as a [https://pkgs.alpinelinux.org/package/edge/community/x86_64/hyprland-plugins package]. Checkout the subpackages to install individual plugins.

=== loading plugins ===

{{Cat|~/.config/hypr/hyprland.conf|<nowiki>plugin = /usr/lib/libhyprexpo.so
plugin {
hyprexpo {
columns = 3
gap_size = 0
workspace_method = first 1
}
}
</nowiki>}}

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 [https://wiki.hyprland.org/Useful-Utilities/Wallpapers/ wallpaper utility], but the scary message remains.

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

{{Cmd|# apk add hyprland-wallpapers}}

Or you can just have some file at {{Path|/usr/share/hypr/wall0.png}} or {{Path|/usr/local/share/hypr/wall0.png}} and modify your config file to have a line as follows: {{Cat|~/.config/hypr/hyprland.conf|<nowiki>misc {
force_default_wallpaper = 0
}</nowiki>}}

=== 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 {{pkg|xwayland}}, or disable in your config:

{{Cat|~/.config/hypr/hyprland.conf|<nowiki>xwayland:enabled = false</nowiki>}}

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.

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

You can disable the check in your config like so:

{{Cat|~/.config/hypr/hyprland.conf|<nowiki>misc:disable_hyprland_qtutils_check = true</nowiki>}}

=== DBUS_SESSION_BUS_ADDRESS unset ===

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

Exec=dbus-run-session -- Hyprland

== See Also ==

* [https://wiki.hyprland.org Official Hyprland wiki]

[[Category:compositor]]