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.

Alpine Linux Hardware Support Matrix
Architecture	Port	Description	Since
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.

Manual method

Alternatively, the Alpine Linux image/tarball for Raspberry Pi may be downloaded, and SD card install media can be prepared. Use the compatibility 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.

• For image file i.e img.gz, follow the regular installation media preparation steps to create a SD card which can be used as a customizable boot device.

• For tarball i.e tar.gz, the SD card needs to be prepared i.e partitioned and formatted first.

1. 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 FAT partition. Due to an upstream firmware 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 FAT partition.

   
   

2. Extract the tarball to the root of the bootable FAT32 partition.

Note: Using image file or Raspberry Pi Imager will create a minimum-sized FAT16 volume with only about 8MB of free space. If using same media for Diskless/Data-disk Modes with large add-on packages, you may want to grow that partition for more ample packages cache storage, or follow the tarball Manual method and allocate optimal partition size.

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 perform standard procedures for actual install and initial base setup.

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 noteworthy settings include:

• dtparam=audio=on to enable audio support with snd_bcm2835 driver for onboard audio jack and legacy hdmi audio mode.
• 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).
• Enabling default serial console with enable_uart=1, together with console=serial0,115200 in cmdline.txt kernel parameters list.
• 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).
• If you plan to install on a Pi Computer Module 4 with I/O board, you may need to add: otg_mode=1

Update the System

After installation, check and apply updates to keep your system secure.

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 Zero/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 Zero-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, for instance, serial gadget may be enabled with echo "g_serial" | tee -a /etc/modules-load.d/gadget.conf (or adding modules=g_serial in cmdline.txt).

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

Picam

Note: The below instructions has been tested only in sys mode install with Pi Zero 2W.

1. To use rpicam-apps package, upgrade to edge branch.
2. Setup eudev as device manager:

   # setup-devd udev

3. Add camera_auto_detect=1 option to the user config file /boot/usercfg.txt
4. Install the package rpicam-apps available in the testing repository.
5. Due to bug #16911, change the permission after every reboot as follows:

   $ doas chmod 666 /dev/dma_heap/*

6. Test the picam by the command

   $ libcamera-hello --list-cameras

Resize partition created with image file

Media created from image file (manually or with Raspberry Pi Imager) can cautiously be resized up to 128MB(as base image is created as FAT16 with 2k clusters) with fdisk (parted-based tools may fail doing so).
Proceed with care to delete d, and then n recreate primary partition of desired size-1MB (will start at sector 2048 by default), change it to 06 (FAT16) with t command, and go to x extra menu and then b (move beginning of data in a partition to 0 -- mind this increases size by 2048 sectors=1MB). Finally return r and write w new partition table.
Then filesystem needs to be resized accordingly with fatresize.
This should not destroy existing data.
For exemple scripting it (128MB size):

doas fdisk /dev/sda <<EOF d n p 1 2048 +127M t 06 x b 0 r w EOF doas fatresize -s 128M /dev/sda

Custom installation instructions

• 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

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 with only 512M of RAM (i.e. Zero, 3A+), a fresh Alpine Linux installation in Diskless mode will only leave around 200M for tmpfs root. Such 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

See also

• Classic install or sys mode on Raspberry Pi
• Raspberry Pi 3 - Setting Up Bluetooth
• Raspberry Pi 3 - Configuring it as wireless access point -AP Mode
• Raspberry Pi 3 - Browser Client
• Linux Router with VPN on a Raspberry Pi
• Netbooting Raspberry Pi
• Create a bootable SDHC from a Mac
• OverlayFS‎‎
• Build custom Raspberry Pi images based on Alpine via Pieman
• Tutorials and Howtos#Raspberry Pi