Raspberry Pi

2026-03-05T15:08:38Z

Habchab: /* Serial ports & console */

{{TOC right}}

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

== Compatibility list ==

Refer to the information regarding Raspberry Pi models in the below table when choosing image/file to download from [https://alpinelinux.org/downloads/ Downloads] page for your device. [[Installation#Verifying_downloaded_image|Verify]] the downloaded image before proceeding further.
{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
!Port !! Raspberry Pi Models
|-
|armhf || Pi 1, Zero, ZeroW, cm1 ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835 BCM2835] devices with [https://www.raspberrypi.com/documentation/computers/configuration.html#kernel-files-img v6] kernel and [https://www.raspberrypi.com/documentation/computers/linux_kernel.html#native-build-configuration bcmrpi_defconfig])
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+ ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2836 BCM2836] and [https://www.raspberrypi.com/documentation/computers/processors.html#bcm2837 BCM2837A/B0, RP3A0] devices with [https://www.raspberrypi.com/documentation/computers/configuration.html#kernel-files-img v7] kernel and [https://www.raspberrypi.com/documentation/computers/linux_kernel.html#native-build-configuration bcm2709_defconfig])
|-
| aarch64 || Pi 2 (rev 1.2+), 3, 3+, Zero2W, cm0, cm3, cm3+, 4, 400, cm4, 5, 500, 500+, cm5 ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2837 BCM2837A/B0, RP3A0], [https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711 BCM2711] and [https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712 BCM2712] devices with [https://www.raspberrypi.com/documentation/computers/configuration.html#kernel-files-img v8] kernel and [https://www.raspberrypi.com/documentation/computers/linux_kernel.html#native-build-configuration bcm2711_defconfig])
|}

== Fine-tuned support ==

<code>linux-rpi</code> packaged kernels are the '''''supported kernels''''' shipped within Alpine's ''Raspberrypi install releases''. 
These kernels are built with ''Pi Foundation's downstream patches and [https://gitlab.alpinelinux.org/alpine/aports/-/blob/9ad68e613f9fa26d184f5b8d21fa679fca15e8e0/main/linux-rpi/APKBUILD#L68-70 defconfigs]'' files (with few [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/main/linux-rpi/common-changes.config minor deviations]): therefore user should expect features parity with PiOS shipped kernels.

Other available [[Kernels|generic kernels]] like <code>linux-lts</code> are built from upstream with ''Alpine's distro [https://gitlab.alpinelinux.org/alpine/aports/-/tree/master/main/linux-lts generic defconfigs]'': <code>armv7</code> or <code>aarch64</code> instances may be used with related Pi devices. However, they may not fully support all expected Pi device features, and may require different/additional configurations steps and are '''unsupported'''.

The {{pkg|linux-firmware|arch=}} package bundles {{pkg|linux-firmware-brcm|arch=}} containing ''downtream Pi Foundation's'' shipping [https://github.com/RPi-Distro/firmware-nonfree wifi] and [https://github.com/RPi-Distro/bluez-firmware bluetooth] firmware files for Pi devices: it ensures optimal support for wireless connectivity (on par with PiOS community).

Several Pi-specific {{pkg|raspberrypi-*|arch=}} packages are provided to further tune support: some are installed by default within supported Pi releases, some others are optional from <code>community</code> repo.

== Preparing the installation media ==

=== Raspberry Pi Imager ===

[https://www.raspberrypi.com/news/raspberry-pi-imager-imaging-utility 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 [https://github.com/raspberrypi/rpi-imager/releases 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 {{pkg|rpi-imager}} package from [[Repositories#Using_testing_repository|testing]] repository. To launch the utility in graphical mode issue the command: {{Cmd|rpi-imager}}

'''--cli''' option is also available. For complete usage guide, check out the <code>rpi-imager(1)</code> manpages, which you can [[install]] with the {{Pkg|rpi-imager-doc}} package.

=== Manual method ===

Alternatively, the Alpine Linux image/tarball for Raspberry Pi may be [https://alpinelinux.org/downloads/ downloaded], and SD card install media can be prepared. Use the [[#Compatibility list|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 <code>blkdiscard /dev/mmcblk0</code> to ensure [https://man7.org/linux/man-pages/man8/blkdiscard.8.html device sectors are discarded] before re-partitioning.}}

* For image file i.e ''img.gz'', follow the regular [[Installation#Preparing installation media|installation media preparation steps]] to create a SD card which can be used as a [[Create a Bootable Device|customizable boot device]].

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

# Create a '''FAT32''' partition and format it using a graphical partitioning tool such as [https://en.wikipedia.org/wiki/GNOME_Disks gnome-disks] or [https://gparted.org gparted]: just make sure the partition type is <code>W95 FAT32 (LBA)</code>. (The current type can be found in the "Type" column in the output of <code>fdisk -l</code>.)
#: {{warning|Do not use the volume label <code>boot</code> for the FAT partition. Due to an upstream firmware [https://github.com/raspberrypi/firmware/issues/1529 bug], kernel/initramfs cannot be loaded from subdirectory with same name as volume label. Since kernel is installed to <code>boot/</code> folder in Alpine Linux, do not use the volume label <code>boot</code> for the FAT partition.}}
#:For example with {{pkg|sfdisk}} and {{pkg|dosfstools}}: {{Cmd|<nowiki>echo 'start=2048, size=300M, type=c, bootable' | doas sfdisk /dev/mmcblk0</nowiki> doas mkfs.vfat -n PIBOOT -F 32 /dev/mmcblk0p1}}
# Extract the tarball to the root of the bootable FAT32 partition.

{{Note|Using image file (manually or with Raspberry Pi Imager) will create a minimum-sized FAT16 partition. While enough for most use-cases, it may prove insufficient if using same media for Diskless/Data-disk Modes with many large add-on packages: one may then want to [[#Resize partition created with image file|grow that partition]] for more ample packages cache storage, or follow the tarball [[#Manual method|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 [[Installation#Installation_Overview|diskless/data disk/system disk]].

[[Diskless Mode|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)

[[Classic install or sys mode on Raspberry Pi|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 [[OverlayFS#Immutable_root_with_tmpfs_overlay|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 [[Installation on a headless host|headless Installation]] page.}}

Once [[#Preparing the installation media|install media is prepared]], proceed to perform [[Installation#Base_configuration|standard procedures]] for actual install and initial base setup. 
(As most Pi devices do not have RTC, make sure to add a NTP service during <code>setup-alpine</code> or set date manually beforehand).

After install and reboot, check notes below for further customization and [[#Troubleshooting| 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 [https://www.raspberrypi.com/documentation/computers/config_txt.html#include settings] can only be set within '''config.txt''', and will have no effect when specified in '''usercfg.txt''' (e.g. <code>gpu_mem</code>). All available settings information can be found [https://www.raspberrypi.com/documentation/computers/config_txt.html here]. 
Some noteworthy settings include:
* <code>dtparam=audio=on</code> to enable audio support with <code>snd_bcm2835</code> driver for onboard audio jack and legacy hdmi audio mode.
* By default system will use ''legacy video driver'': some [https://www.raspberrypi.com/documentation/computers/legacy_config_txt.html#legacy-video-options 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 <code>disable_overscan=1</code>). Alternatively, better supported ''Linux DRM-KMS driver'' may be used (see setup[[#Linux_Kernel_Graphics_Modes| below]]).
* To maximize available CPU memory if not requiring extra GPU features (i.e. headless/CLI use-cases), cut-down bootloader may be installed with {{Pkg|raspberrypi-bootloader-cutdown|arch=}} package, and activated by adding <code>gpu_mem=16</code> in '''config.txt''' (setting may be wiped after bootloader package update).
* To use a camera, Pi firmware can try to load adequate driver overlay if [https://www.raspberrypi.com/documentation/computers/config_txt.html#camera_auto_detect <code>camera_auto_detect=1</code>] is set. If failing, set <code>camera_auto_detect=0</code> and explicitly add [https://www.raspberrypi.com/documentation/computers/camera_software.html#configuration relevant overlay for camera].
* If you plan to install on a Pi Computer Module 4 with I/O board, you may need to add: <code>otg_mode=1</code>

=== Update the System ===

After installation, [[Alpine_Package_Keeper#Upgrade_a_Running_System|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 [https://forums.raspberrypi.com/viewtopic.php?t=310315#p1856052 lower-ram devices] (i.e. Pi Zero/1), this driver has some limitations and is now lacking support. 
Linux DRM-KMS driver is [https://forums.raspberrypi.com/viewtopic.php?t=317511#p1900440 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|<code>vc4-kms-v3d</code> overlay:
* ignores legacy video [https://www.raspberrypi.com/documentation/computers/legacy_config_txt.html#legacy-video-options options] from '''usrcfg.txt''' / '''config.txt'''.
* enables Linux HDMI audio support by [https://www.raspberrypi.com/documentation/computers/config_txt.html#hdmi-audio default]. Eventual onboard audio jack still needs legacy <code>snd_bcm2835</code> driver through <code>dtparam{{=}}audio{{=}}on</code> option in '''usrcfg.txt'''.
* enables HDMI cec device within <code>/sys/class/rc</code>, supported through standard {{pkg|libcec|arch=}}.}}

3D Mesa drivers may be also added for [https://docs.mesa3d.org/drivers/vc4.html vc4] (Pi Zero-3) or [https://docs.mesa3d.org/drivers/v3d.html v3d] (Pi 4-5) devices:{{cmd|apk add {{pkg|mesa-dri-gallium|arch=}}}}
[https://forums.raspberrypi.com/viewtopic.php?t=363368#p2179572 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 <code>linux-firmware-brcm</code> (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 [https://github.com/raspberrypi/rpi-firmware/tree/master/overlays krnbt] off).

Adding the following file to disable roaming and few other <code>brcmfmac</code> driver features [https://github.com/RPi-Distro/firmware-nonfree/commit/e1e78b65b350c799cb7cac49713e21c79fcf993d may improve wifi stability]. 
<code>$cat /etc/modprobe.d/brcmfmac.conf 
options brcmfmac roamoff=1 feature_disable=0x282000</code>

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

{{Note|On Alpine 3.22.0, aforementioned <code>brcmfmac</code> driver options '''must''' be applied to circumvent an issue due to [https://gitlab.alpinelinux.org/alpine/aports/-/issues/17195 shipping <code>wpa_supplicant</code>]. This is fixed from 3.22.1.}}

=== USB-gadget ===

Pi Zeros/A/A+/3A+/4B/400/5/500/CMs may be configured in various [https://trac.gateworks.com/wiki/linux/OTG#USBDeviceMode 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... (check [https://pip-assets.raspberrypi.com/categories/685-app-notes-guides-whitepapers/documents/RP-009276-WP-1-Using%20OTG%20mode%20on%20Raspberry%20Pi%20SBCs.pdf whitepaper] for detailed info)

This may be achieved by loading relevant drivers & options in early boot sequence: in any case <code>dtoverlay=dwc2,dr_mode=peripheral</code> must be added to '''usercfg.txt'''. 
Then, for instance, serial gadget may be enabled with <code>echo "g_serial" | tee -a /etc/modules-load.d/gadget.conf</code> (or adding <code>modules=g_serial</code> in '''cmdline.txt''').

{{Tip|community <code>{{pkg|xg_multi|arch=}}</code> package may ease setup for serial/ethernet/mass-storage composite gadget, while ensuring interoperability across most host OS.}}

=== Serial ports & console ===

Depending on Pi devices and '''usercfg.txt''' configurations, different ''UART''s may be configured: refer to [https://www.raspberrypi.com/documentation/computers/configuration.html#configure-uarts devices documentation] for details. 
Usually <code>/dev/ttyAMA0</code> maps into first <code>PL011</code> (on GPIOs), and if activated, <code>/dev/ttyS0</code> into so-called [https://www.raspberrypi.com/documentation/computers/configuration.html#mini-uart-and-cpu-core-frequency <code>mini UART</code>] (has some limitations).

Alpine does not setup [https://github.com/RPi-Distro/raspberrypi-sys-mods/blob/pios/trixie/usr/lib/udev/rules.d/99-com.rules PiOS's specific symlinks] <code>/dev/serial0</code> and <code>/dev/serial1</code>.

Change <code>console=</code> parameter from '''cmdline.txt''' to desired serial port to set it as kernel console (may block or delay boot if improperly set).

The boot process may be interrupted if there is UART traffic going to the Pi upon power up. This may be because U-Boot sees this as a keypress, stopping the autoboot process to give a prompt and wait forever for a command. To disable this behavior, add [https://docs.u-boot.org/en/latest/usage/environment.html <code>bootdelay=-2</code>] to '''usercfg.txt'''.

=== Camera ===

With camera enabled in [[#Customize_config.txt_and_usercfg.txt| '''usercfg.txt''']] file, the command {{Codeline|$ libcamera-hello --list-cameras}} from the {{pkg|rpicam-apps|arch=}} package in the [[Repositories#Testing|testing]] repository can be used to check camera availability.

=== Resize partition created with image file ===

Since Alpine 3.23, media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can have partitions seamlessly resized with <code>parted</code>-based tools (mind a [https://gitlab.gnome.org/GNOME/gparted/-/issues/298 <code>gparted</code> bug] if partition gets converted into FAT32 in the process).

On pre-3.23 releases, media can '''cautiously''' be grown up-to maximum 128MB (as base image is created as [https://www.pctechguide.com/hard-disks/file-systems-fat-fat8-fat16-fat32-and-ntfs-explained FAT16 with 2k clusters]) with <code>[https://serverfault.com/questions/994448/extend-linux-partition-size-without-losing-any-data-techniques fdisk]</code> (<code>parted</code>-based tools may fail doing so). 
Proceed with care to delete <code>d</code>, and then <code>n</code> recreate primary partition of desired size-1MB (will start at sector 2048 by default), change it to <code>06</code> (FAT16) with <code>t</code> command, and go to <code>x</code> extra menu and then <code>b</code> (move beginning of data in a partition to <code>0</code> -- mind this increases size by 2048 sectors=1MB). Finally return <code>r</code> and write <code>w</code> new partition table. 
Then filesystem needs to be resized accordingly with <code>fatresize</code>. 
This should not destroy existing data, e.g. with following script (128MB size):
{{Cmd|<nowiki>printf '%s\n' d n p 1 2048 +127M t 06 x b 0 r w | doas fdisk /dev/mmcblk0</nowiki>
doas fatresize -n 1 -s 128M /dev/mmcblk0}}

== Custom installation instructions ==

* [[Classic_install_or_sys_mode_on_Raspberry_Pi#Convert diskless to sys mode|Convert diskless to sys mode]].
* An alternate approach [[OverlayFS#Loopback image with overlayfs|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 ==

<code>raspinfo</code> utility from the {{Pkg|raspberrypi-utils-raspinfo|arch=}} 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 <Code>vcgencmd</Code> utility from the {{pkg|raspberrypi-utils-vcgencmd|arch=}} package as follows:{{Cmd|<nowiki># vcgencmd get_mem gpu
# vcgencmd get_mem arm</nowiki>}}

To modify the memory allocation refer to ''legacy'' [https://www.raspberrypi.com/documentation/computers/legacy_config_txt.html#gpu_mem 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 [[Diskless_Mode#Modifying_root_filesystem_size| tuned]] or alternative install modes shall be [[#Considerations_for_choosing_install_modes| 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, <code>setup-alpine</code> will adapt the installation to the type of Raspberry Pi you use, which means for example that on a RPI5, you will see <code>hwclock></code> service, whereas on a RPI4 it will use <code>swclock</code>. 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''':

<code>makestep 0.1 3</code>

=== Wireless support with older Alpine images ===

In Alpine 3.14, the WiFi drivers for the Raspberry Pi were moved from <code>linux-firmware-brcm</code> to the <code>linux-firmware-cypress</code> 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:

{{cmd|apk add {{pkg|linux-firmware-cypress|arch=a*}}}}

And reboot.

If you need Wi-Fi, you'll need to [https://github.com/RPi-Distro/firmware-nonfree/tree/master/brcm 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 [https://github.com/tolstoyevsky/pieman Pieman]
* [[Tutorials and Howtos#Raspberry Pi]]
* Raspberry Pi technical [https://www.raspberrypi.com/documentation/ documentation] and [https://pip.raspberrypi.com/categories/685-app-notes-guides-whitepapers whitepapers]

[[Category:Installation]]
[[Category: Raspberry]]

Alpine Linux - User contributions [en]

Raspberry Pi