Raspberry Pi

Raspberry Pi devices are well supported on Alpine Linux by default. This page enlightens few specific information like install media creation, post-install customization and troubleshooting.

Compatibility list

Refer to the information regarding Raspberry Pi models in the below table when choosing image/file to download from Downloads page for your device. Verify the downloaded image before proceeding further.

Architecture	Port	Description	Since
Alpine Linux Hardware Support Matrix
ARM	armhf	32 bit ARM with hard-float ABI - for ARMv6 devices- Raspberry Pi 1, Zero, ZeroW, cm1 (defconfig bcmrpi)	v3.0
	armv7	32 bit ARM - for ARMv7 devices - Raspberry Pi 2, 3, 3+, Zero2W, cm3, cm3+ (defconfig bcm2709)	v3.9
	aarch64	64 bit ARM - for ARMv8+ devices - Raspberry Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5 (defconfig bcm2711)	v3.5

Preparing the installation media

Raspberry Pi Imager

Raspberry Pi Imager is a GUI utility for creating distributions install media for Pi devices in few clicks: it takes care of downloading, partitioning and formatting. Pre-built binaries are available for Linux/macOS/Windows.

Alpine Linux is listed under Other general-purpose OS section from Choose OS tab.

This utility can also be used from an Alpine linux system: install the rpi-imager package from testing repository. To launch the utility in graphical mode issue the command:

rpi-imager

--cli option is also available. For complete usage guide, check out the rpi-imager(1) manpages, which you can install with the rpi-imager-doc package.

Note: Raspberry Pi Imager will create a minimum-sized FAT32 partition with only about 8MB of free space. If you need a bigger partition (i.e. with more available room for diskless packages cache and config files), you may want to grow that partition afterwards, or follow the Manual method below.

Manual method

Alternatively, image or tarball may be downloaded, and SD card media formatted and prepared as per below:

Download the Alpine Linux image/tarball for Raspberry Pi . Use the compability list above when choosing image/tarball to download.
Tip: To reduce SD wear risk, it is advised to keep at least 10% of capacity as unallocated space. If partitioned previously at full capacity, run blkdiscard /dev/mmcblk0 to ensure device sectors are discarded before re-partitioning.
Use the instructions on Create a Bootable Device page or Create a FAT32 partition and format it using a graphical partitioning tool such as gnome-disks or gparted: just make sure the partition type is W95 FAT32 (LBA). (The current type can be found in the "Type" column in the output of fdisk -l.)
Warning: Do not use the volume label boot for the fat32 partition. Due to an upstream bug, kernel/initramfs cannot be loaded from subdirectory with same name as volume label. Since kernel is installed to boot/ folder in Alpine Linux, do not use the volume label boot for the fat32 partition.
Extract the tarball to the root of the bootable FAT32 partition.

Considerations for choosing install modes

The installation procedure for Alpine Linux requires basic understanding of the three modes i.e (diskless/data disk/system disk).

Diskless mode may be preferable on a pi with SD Card as the only storage device, as running the entire system from memory will improve performance (by avoiding the slow SD card) and improve the SD card life (by reducing the writes to the card, as all logging will happen in RAM). This mode is suitable for scenarios where there is not expected to be significant changes to disk after setup (like running a static HTTP server)

System disk mode installation may be more appropriate for the following use cases:

There will be constant changes to the disk after initial setup (for example, if you expect people to login and save files to their home directories)
Logs should persist across reboots
Plan to install packages which consume more space than can be loaded into RAM
Plan to install kernel modules (such as ZFS)

System disk mode with Immutable root option can also be a solution to keep whole system on read-only media (lower RAM requirement than diskless mode which loads whole system in RAM) while avoiding SD wear as runtime files are mapped to tmpfs in RAM (check limitations).

Installation

Tip: To install Alpine Linux on a Pi without keyboard, mouse & display, additional preparatory steps for install media are available at headless Installation page.

Once install media is prepared, proceed to standard procedures for actual install and initial base setup. Follow the Pi specific system disk installation page if appropriate.

After install and reboot, check notes below for further customization and troubleshooting.

Post Installation

Customize config.txt and usercfg.txt

Instead of the BIOS found on a conventional PC, Raspberry Pi devices use a configuration file called config.txt. The GPU reads config.txt before the Arm CPU and Linux initialise. It is recommended to create a custom usercfg.txt file on boot partition to configure low-level system settings, as config.txt may be replaced during bootloader/system upgrades. However, few settings can only be set within config.txt, and will have no effect when specified in usercfg.txt (e.g. gpu_mem). All available settings information can be found here.

Some interesting values include:

Contents of usercfg.txt

enable_uart=1 # To enable the UART console:
dtparam=audio=on # To enable audio with legacy snd_bcm2835 driver

By default system will use legacy video driver: some options may be used to adjust displays modes (e.g. if you see black edges around your screen after booting the Pi, you can add disable_overscan=1). Alternatively, better supported Linux DRM-KMS driver may be used (see setup below).
If you plan to install on a Pi Computer Module 4 with I/O board, you may need to add: otg_mode=1
To maximize available CPU memory if not requiring extra GPU features (i.e. headless/CLI use-cases), cut-down bootloader may be installed with raspberrypi-bootloader-cutdown package, and activated by adding gpu_mem=16 in config.txt (setting may be wiped after bootloader package update).

Update the System

After installation, make sure your system is up-to-date:

apk update apk upgrade

Tip: If on diskless mode:

don't forget to save changes after any system or configuration files update with lbu commit -d
in order to upgrade the kernel, follow update-kernel script procedure.

Linux Kernel Graphics Modes

By default system configuration will use legacy video driver: while it may remain well suited for lower-ram devices (i.e. Pi O/1), this driver has some limitations and is now lacking support.
Linux DRM-KMS driver is recommended for most devices: it is enabled by adding the following to usercfg.txt:

# Enable DRM VC4 V3D driver
dtoverlay=vc4-kms-v3d
max_framebuffers=2

# Don't have the firmware create an initial video= setting in cmdline.txt.
# Use the kernel's default instead.
disable_fw_kms_setup=1

Note: vc4-kms-v3d overlay:

ignores legacy video options from usrcfg.txt / config.txt.
enables Linux HDMI audio support by default. Eventual onboard audio jack still needs legacy snd_bcm2835 driver through dtparam=audio=on option in usrcfg.txt.
enables HDMI cec device within /sys/class/rc, supported through standard libcec.

3D Mesa drivers may be also added for vc4 (Pi 0-3) or v3d (Pi 4-5) devices:

apk add mesa-dri-gallium

vc4 devices limitations in memory management may require regular reboots.

Wireless drivers

As of Alpine 3.17, Wifi and Bluetooth drivers are available within install image: they are part of linux-firmware-brcm (and linked dependencies). Since kernel 6.1.25 (i.e. Alpine 3.18), onboard bluetooth is enabled & autoprobed by default. This may be disabled by setting krnbt off).

Adding the following file to disable roaming and few other brcmfmac driver features may improve wifi stability.
$cat /etc/modprobe.d/brcmfmac.conf options brcmfmac roamoff=1 feature_disable=0x282000

Alternatively same parameters may be passed all-in-one-line to kernel from cmdline.txt as:
brcmfmac.roamoff=1 brcmfmac.feature_disable=0x282000

Note: On Alpine 3.22.0, aforementioned brcmfmac driver options must be applied to circumvent an issue due to shipping wpa_supplicant. This is fixed from 3.22.1.

USB-gadget

Pi Zeros/A/A+/3A+/4B/400/5/500/CMs may be configured in various USB-gadget roles (or a composite combination thereof) connected to host via USB: such roles may be serial-gadget (i.e. console access for setup), ethernet-gadget for networking, mass-storage (appear as USB disk), webcam, keyboard, etc...

This may be achieved by loading relevant drivers & options in early boot sequence: in any case dtoverlay=dwc2,dr_mode=peripheral must be added to usercfg.txt.
Then serial gadget for exemple may be enabled by adding modules=g_serial in cmdline.txt.

Tip: community xg_multi package may facilitate setup for serial/ethernet/mass-storage composite gadget, while ensuring interoperability across most host OS.

Picam

Note: The below instructions to get picam to work with Pi Zero 2 W model has been tested in sys mode only.

Upgrade to edge version as rpicam-apps package is not yet supported in v3.21.
Setup eudev as device manager:
# setup-devd udev
Add camera_auto_detect=1 option to the user config file /boot/usercfg.txt
Install the package rpicam-apps available in the testing repository.
Due to bug #16911, change the permission after every reboot as follows:
$ doas chmod 666 /dev/dma_heap/*
Test the picam by the command
$ libcamera-hello --list-cameras

Resize partition created by rpi-imager

The partition created by rpi-imager can cautiously be resized with fdisk, taking care to delete d, and then n recreate primary partition of desired size, change it to 0e (FAT16) with t command, and go to x extra menu and then b (move beginning of data in a partition to 0). Finally write w new partition table. This should not destroy existing data.

Custom installation instructions

To switch a Diskless installation to a fully disk-based installation refer Convert diskless to sys mode.
An alternate approach using loopback image with overlayfs for memory constrained Raspberry Pi models (3A+,Pi Zero) with only 512M of RAM running Diskless mode.
Netbooting Raspberry Pi device

Enable the Serial Console

Besides having enable_uart=1 in usercfg.txt, the kernel command-line option console needs to be changed to console=serial0,115200 in cmdline.txt.

From a Linux desktop, connect to it with something like this:

cu -l /dev/ttyUSB0 -s 115200

Troubleshooting

raspinfo utility from the raspberrypi-utils-raspinfo package can be used as a first step to diagnose issues: it will make a log report of essential Pi system configuration, and is often used as a reference to submit questions or bug reports within Raspberry Pi community (Forums, Github, etc).

After booting, you may find less system memory available than you expect, as default CPU/GPU RAM split depends on Pi models and activated settings (audio, camera, video drivers, etc). To find out how your system is actually split, use vcgencmd utility from the raspberrypi-utils-vcgencmd package as follows:

# vcgencmd get_mem gpu # vcgencmd get_mem arm

To modify the memory allocation refer to legacy gpu_mem parameter information for config.txt.

Long boot time when running headless

If no peripherals are connected, the system might hang for an exceptionally long period of time while it attempts to accumulate entropy.

If this is the case, simply plugging in any USB device should work around this issue, since it increases the amount of entropy available to the kernel via interrupts.

apk indicating 'No space left on device'

While running Raspberry Pi models(3A+,Pi0) with only 512M of RAM, a fresh Alpine Linux installation in Diskless mode will only leave around 200M for tmpfs root. Allocation may be tuned or alternative install modes shall be considered.

Clock-related error messages

During the booting time, you might notice errors related to the hardware clock. Many Raspberry Pi do not have a hardware clock, or may have one without battery, in which case the behaviour depends on whether you physically cut power or not.

Also, setup-alpine will adapt the installation to the type of Raspberry Pi you use, which means for example that on a RPI5, you will see hwclock> service, whereas on a RPI4 it will use swclock. In doubt, make sure to do the installation on the target hardware.

If you still experience clock errors, add the following line to /etc/chrony/chrony.conf:

makestep 0.1 3

Wireless support with older Alpine images

In Alpine 3.14, the WiFi drivers for the Raspberry Pi were moved from linux-firmware-brcm to the linux-firmware-cypress package (source?). Since the images seem to be an outdated version of the former, Wi-Fi will work during installation, but after the first update it will break. Use the ethernet interface to download the required packages:

apk add linux-firmware-cypress

And reboot.

If you need Wi-Fi, you'll need to download the latest Broadcom drivers to your SD card. (Replace /mnt/sdcard with the correct mount point.)

 git clone --depth 1 https://github.com/RPi-Distro/firmware-nonfree.git
 cp firmware-nonfree/brcm/* /mnt/sdcard/firmware/brcm

Filesystem for boot partition

If you are trapped at the dreaded rainbow screen, with the green led blinking a few times in a row, repeatedly, check the boot partition type.

The rpi2 require fat32 for the boot partition, NOT fat16. Use linux fdisk to set the boot partition type as "c" (for fat32/lba) and set the lba and boot flags for the partition as suggested. Create the boot partition filesystem as fat32 with:

mkdosfs -F 32 /dev/sdX1