Alpine Linux - User contributions [en]

Raspberry Pi

2026-01-19T09:57:05Z

Macmpi: /* Compatibility list */

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

=== 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]]

Raspberry Pi

2026-01-17T10:15:29Z

Macmpi: /* See also */ ref Pi technical documentation and whitepapers

{{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 BCM2837] 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 || later Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+, 4, 400, cm4, 5, 500, 500+, cm5 ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2837 BCM2837], [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).

=== 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]]

Raspberry Pi

2026-01-17T10:05:42Z

Macmpi: /* USB-gadget */ reference whitepaper

{{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 BCM2837] 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 || later Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+, 4, 400, cm4, 5, 500, 500+, cm5 ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2837 BCM2837], [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).

=== 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]]

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

Raspberry Pi

2026-01-16T15:21:50Z

Macmpi: /* Compatibility list */

{{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 BCM2837] 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 || later Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+, 4, 400, cm4, 5, 500, 500+, cm5 ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2837 BCM2837], [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...

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

=== 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]]

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

Raspberry Pi

2026-01-15T11:13:43Z

Macmpi: /* Compatibility list */ add kernel variant

{{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 BCM2837] 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 || later Pi 2, Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5 ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2837 BCM2837], [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...

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

=== 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]]

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

Raspberry Pi

2026-01-15T10:55:38Z

Macmpi: add bcm parts and defconfigs ref

{{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/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 BCM2837] devices with [https://www.raspberrypi.com/documentation/computers/linux_kernel.html#native-build-configuration bcm2709_defconfig])
|-
| aarch64 || later Pi 2, Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5 ([https://www.raspberrypi.com/documentation/computers/processors.html#bcm2837 BCM2837], [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/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...

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

=== 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]]

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

Talk:Zram

2026-01-11T12:32:48Z

Macmpi:

Advanced setups may also add these parameters to /etc/sysctl.conf as follows
Would be nice to add more explanations and references (like [https://wiki.archlinux.org/title/Zram#Optimizing_swap_on_zram this]?).
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 12:50, 11 Jan 2025 (UTC)

Talk:Zram

2026-01-11T12:17:31Z

Macmpi: advanced settings

Advanced setups may also add these parameters to /etc/sysctl.conf as follows
Would be nice to add more explanations and references.
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 12:50, 11 Jan 2025 (UTC)

Zram

2026-01-11T12:13:34Z

Macmpi: /* Configuration */ add zramctl

This page documents how to set up [https://docs.kernel.org/admin-guide/blockdev/zram.html ZRAM] in Alpine Linux. Zram can be used as an alternative to [[Swap]] partition.

== Installation ==

Install the neccessary packages:{{Cmd|# apk add {{pkg|zram-init}}}}

== Configuration ==

For a basic ZRAM swap, configure ZRAM by editing the file {{path|/etc/conf.d/zram-init}} as follows:{{Cat|/etc/conf.d/zram-init|<nowiki>load_on_start=yes
unload_on_stop=yes
num_devices=1
type0=swap
size0=8000
</nowiki>}}

Advanced parameters can be found in the [https://github.com/vaeth/zram-init/blob/main/openrc/conf.d/zram-init source repo].

Start services:{{Cmd|# rc-service zram-init start}}

Check overall status: {{Cmd|# zramctl}}

View the ZRAM drive:{{Cmd|# cat /proc/swaps}}

Check Algorithms:{{Cmd|# cat /sys/block/zram0/comp_algorithm}}

Advanced setups may also add these parameters to {{path|/etc/sysctl.conf}} as follows:{{Cat|/etc/sysctl.conf|<nowiki>vm.page-cluster=0
vm.extfrag_threshold=0
vm.swappiness=100</nowiki>}}

To ensure that service starts during next reboot: {{Cmd|# rc-update add zram-init}}

== Troubleshooting ==

Check whether ZRAM's module is loaded: {{Cmd|# lsmod | grep zram}}

If not loaded, use <code>modprobe</code> to load it: (however, it should be automatically loaded if <code>load_on_start=yes</code> is in the configuration) {{Cmd|# modprobe zram}}

== See also ==

* [https://github.com/vaeth/zram-init/blob/main/openrc/conf.d/zram-init sample zram-init file on official website]
* [https://wiki.archlinux.org/title/Zram Zram in Arch Wiki]
* [https://en.wikipedia.org/wiki/zram Zram in Wikipedia]

[[Category:System Administration‏‎]]
[[Category:Storage‏‎‏‎]]
[[Category:Kernel]]

Raspberry Pi

2025-12-11T12:18:29Z

Macmpi: /* Manual method */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

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

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

=== 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]]

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

Raspberry Pi

2025-12-11T12:15:28Z

Macmpi: /* Manual method */ add cli partition/format example

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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 exemple 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 --offset 2048 /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...

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

=== 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]]

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

Installation on a headless host

2025-12-09T11:39:51Z

Macmpi: /* Headless bootstrap overlay file */

This page documents an easy installation procedure for Alpine Linux on a headless host i.e a system without keyboard, mouse & display to interact with but otherwise available only through a network connection. Somebody has to insert the Install media and power up the headless host. This procedure applies to '''all''' platforms.

== Headless bootstrap overlay file ==

The [https://github.com/macmpi/alpine-linux-headless-bootstrap Headless bootstrap] repo provides a ready-to-use overlay file to bootstrap a headless system.

While straightforward in default use-case, many optional settings and advanced modes are detailed on repo homepage (unattended installs scripting, secured logon, ssh keys configuration, gadget-modes, etc).

{{Note|The author of above repo macmpi also maintains a number of [https://pkgs.alpinelinux.org/packages?name{{=}}&branch{{=}}edge&repo{{=}}&arch{{=}}&maintainer{{=}}macmpi packages] for Alpine Linux.}}

To Install Alpine Linux on a headless host, just add [https://github.com/macmpi/alpine-linux-headless-bootstrap headless.apkovl.tar.gz] overlay file as-is (along with optional config files) at the root of [[Create a Bootable Device|customizable boot device]], or of a side media.

If using wifi networking, create a file {{Path|wpa_supplicant.conf}} in the same location as follows:{{Cat|wpa_supplicant.conf|<nowiki>country=FR

network={
key_mgmt=WPA-PSK
ssid="mySSID"
psk="myPassPhrase"
}</nowiki>}}

Alternately, <code>wpa_passphrase</code> utility from {{pkg|wpa_supplicant}} package can be used to create the encrypted version of the above file as follows:{{Cmd|$ wpa_passphrase 'mySSID' 'myPassPhrase' > wpa_supplicant.conf}}
The above encrypted version of the {{Path|wpa_supplicant.conf}} file may be placed in the same location.

Boot the system with the above setup: usual [[Installation#Installation_Step_Details|Installation steps]] can then be performed remotely using {{ic|ssh}}

To find the ip of your headless host, one may use the {{ic|nmap}} tool from {{pkg|nmap}} package as follows: {{Codeline|$ nmap -v -sn 192.168.1.0/24}}

== Alternative custom install media preparation steps==

A Custom install media for a headless host can be created using a [[Create a Bootable Device|customizable boot device]] as per the below process.

{{Note|Instead of [[Create a Bootable Device|customizable boot device]], if a read-only boot media is used, then storing the configs require either a separate storage media or server location.}}

* Booting the [[Create a Bootable Device|customizable boot device]] on some computer with a display and keyboard attached, or in a virtual machine, and doing an intermediate "diskless" setup of just the boot media (more details below), i.e. using the offical <code>[[Alpine_setup_scripts#setup-alpine|setup-alpine]]</code> to configure the system's network, possibly for dhcp if needed, a ssh server, and a login user.
* Choosing "disks=none" for now, yet, configure to store configs on the customizable boot device.
* Use <code>[[Alpine_local_backup|lbu commit]]</code> to store the configs as local backup. Then your completed setup, including its securely created own private keys, will readily get (re)loaded on every subsequent (headless) boot from your custom-build <code><hostname>.apkovl.tar.gz</code> stored on the customizable boot device.

==See also==
* [[Create a Bootable Device|Customizable boot device page]]
* [[Diskless Mode#Apkovl|Diskless page with information on apkovl]]
* [[Alpine local backup]]
* [https://github.com/macmpi/alpine-linux-headless-bootstrap/ Bootstrap Alpine Linux on a headless system] using pre-built <code>apkovl</code> overlay file.

[[Category:Installation]]

Docker

2025-12-06T12:30:35Z

Macmpi: /* Docker rootless */ add info on shadow-subids and XDG_RUNTIME_DIR

== Installation ==

The {{Pkg|docker}} package is in the ''community'' repository. See [[Repositories]] how to add a repository.

apk add docker

=== Docker as root ===

To start the Docker daemon at boot, see [[OpenRC]].

rc-update add docker default
service docker start

Connecting to the Docker daemon through its socket requires you to add yourself to the <code>docker</code> group.

addgroup ${USER} docker

{{Warning|Adding users to this group is equivalent to granting them full root access on the host. [https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface See upstream documentation].}}

=== Docker rootless ===

Docker rootless allows unprivileged users to run the docker daemon and docker containers in user namespaces. This is not the same as dockremap explained in the section below. With dockremap the daemon still runs as root.

This requires the {{Pkg|docker-rootless-extras}} package (available in ''community'') and enabling <code>cgroups v2</code>:
edit <code>/etc/rc.conf</code> and set <code>rc_cgroup_mode="unified"</code>. Then start the service on boot:

rc-update add cgroups default

Additionally, install {{Pkg|shadow-subids}} package: <code>/etc/subuid</code> and <code>/etc/subgid</code> files need to be set up as explained in [https://docs.docker.com/engine/security/rootless/ the official documentation]. 
Confirm [https://docs.docker.com/engine/security/rootless/tips/#advanced-usage <code>XDG_RUNTIME_DIR</code>] environment variable (and related directory) are [[Wayland#XDG_RUNTIME_DIR|properly set]].

Now docker can be start from an unprivileged user with

dockerd-rootless

=== Docker Compose ===

{{Pkg|docker-cli-compose}} is in the ''community'' repository starting with Alpine Linux 3.15.

apk add docker-cli-compose

== Isolate containers with a user namespace ==
<pre>
adduser -SDHs /sbin/nologin dockremap
addgroup -S dockremap
echo dockremap:$(cat /etc/passwd|grep dockremap|cut -d: -f3):65536 >> /etc/subuid
echo dockremap:$(cat /etc/passwd|grep dockremap|cut -d: -f4):65536 >> /etc/subgid
</pre>

add to <code>/etc/docker/daemon.json</code>

<pre>
{
"userns-remap": "dockremap"
}
</pre>

''You may also consider these options : ''
"experimental": false,
"live-restore": true,
"ipv6": false,
"icc": false,
"no-new-privileges": false'''''

You'll find all possible configurations [https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file here].

== "WARNING: No {swap,memory} limit support" ==

You might encounter this message when executing <code>docker info</code>.
To correct this situation, we have to enable the <code>cgroup_enable=memory swapaccount=1</code>

=== Grub ===
If you use Grub, add the cgroup condition into <code>/etc/default/grub</code>, then upgrade your grub

<pre>GRUB_CMDLINE_LINUX_DEFAULT="... cgroup_enable=memory swapaccount=1"</pre>

=== Extlinux ===
With Extlinux, you add the cgroup condition, but inside of <code>/etc/update-extlinux.conf</code>

<pre>default_kernel_opts="... cgroup_enable=memory swapaccount=1"</pre>

then update the config and reboot

<code>update-extlinux</code>

== How to use docker ==

Check the [https://docs.docker.com/ official documentation] for details on general usage of docker, including creating and management of containers. Repeating these instructions here be redundant.

Public images can be browsed at the [https://hub.docker.com/ Docker Hub]. These should also serve as further reference on the Dockerfile format.

Official Docker image files are denoted on the website by a special badge.

== See also ==
* [https://www.erianna.com/creating-a-alpine-linux-repository/ Creating and Hosting an Alpine Linux Package Repository for Docker Packages]
* [[Running Alpine in a Docker Container]]
* [https://wiki.archlinux.org/index.php/Docker Docker - ArchWiki]

[[Category:Virtualization]]

Raspberry Pi

2025-12-04T18:27:54Z

Macmpi: /* Wireless drivers */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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...

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

=== 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]]

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

Raspberry Pi

2025-12-04T12:05:04Z

Macmpi: /* Camera */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== 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]]

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

Raspberry Pi

2025-12-04T11:56:12Z

Macmpi: /* Camera */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Camera ===

With camera enabled in [[#Customize_config.txt_and_usercfg.txt| usercfg]] 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]]

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

Raspberry Pi

2025-12-04T11:36:37Z

Macmpi: /* Customize config.txt and usercfg.txt */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Camera ===

Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}. To list cameras like picam connected to pi, the command {{Codeline|$ libcamera-hello --list-cameras}} from the {{pkg|rpicam-apps|arch=}} package in the [[Repositories#Testing|testing]] repository can be used.

=== 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]]

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

Talk:Raspberry Pi

2025-12-04T11:32:51Z

Macmpi: /* Picam */

== Known Bugs ==
Added a warning since I wasted more than an hour trying to boot.
-- [[User:Lucid|Lucid]] Thu, 11 Feb 2021 15:01:24 -0500

== Entropy ==

Added a troubleshooting section since I ran into a few issues that weren't immediately obvious. I'll update the section a bit more later but for the entropy issue I haven't yet found a good solution (appropriate package? haveged with runlevel default didn't help) so put in the best short term fix I could find for now.

It might be a good idea to add a note about tmpfs being ram-limited. On a 3A+ only ~200M is available for / on a basic installation which severely limits the amount of packages that can be installed.

== Persistence ==
Wouldn't it be more reasonable to partition the SD-Card accordingly? That way, you could have FS > 2GB, too. --[[User:Kurushiyama|Kurushiyama]] ([[User talk:Kurushiyama|talk]]) 10:53, 8 October 2016 (UTC)

I have read that using a journalling fs is not a good idea for SD cards as it shortens their life by multiplying the read/writes. Wouldn't ext2 thus be a better fs for persistent overlays? -- [[User:Nevarmaor|Nevarmaor]] ([[User talk:Nevarmaor|talk]]) 21:56, 20 February 2017 (UTC)

Having burned holes in far too many SD Cards I'm writing up some notes to setup a persistent storage running off of [https://en.wikipedia.org/wiki/F2FS F2FS]. I think that should be the default.
-- [[User:Lucid|Lucid]] Thu, 11 Feb 2021 15:01:24 -0500

== Installing Alpine- Linux on raspberry pi zero w (udhcpc fail problem) ==

The existing tutorial for raspberry pi is followed except on the reboot, the udhcpc attempts to connect and fails. I managed to fix this problem by editing the /etc/network/interfaces file and add the line:

iface wlan0 inet dhcp
pre-up wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf #<--This is the line added to pre-start the wpa_supplicant daemon and log on correctly.

I learned this with the help of the tutorial by Jack Wallen: How to Configure Wireless... on linux.com website

== Which version should I use? ==

There are now three versions of Alpine to choose from (armv7, armhf, aarch64), it might be useful to have a table indicating which version is supported on which hardware. (I'm already unclear on why armv7 and armhf, I assume both are 32 bits and armv7 has soft-float-point instead of hard-float-point, but don't all RPi devices have hard-float-point capabilities? It would be useful to have a little text about this.)

As I understand aarch64 only applies to BCM2837 and above chips (ARMv8 and above), which means it can only run on RPi 3 and above (but I believe RPi 3 and above should be able to use the other images since they also support the 32 bits mode).

Conversely I assume armhf should be usable on all RPi.

== New Install on RPi Zero W ==

I finally got my Pi Zero W installation done and encountered during setup and subsequent boots very sketchy network performance in the form of very high packet loss. I overcame this by switching from static IP address (which seemed to break networking scripts) to dhcp by editing the /etc/network/interfaces file. I also edited the /etc/wpa_supplicant/wpa_supplicant.conf file using vi to delete duplicated entries which accumulated while trying to get a decent network connection via wireless.

I then went on to try to install the software which is the purpose of using Alpine for me, mosquitto. This had me stumped as I am using armhf, V3.12, have the 3.12 main, community, edge main and community and testing repos and can see mosquito and mosquito-clients packages in the repository listing but consistently get errors on install. I tried to resolve dependencies by hand via installation on required packages with the result I can install some but not all of these packages. I can install other software such as sshd and nmap but get an almost meaningless to me error about unsatisfiable contraints, mosquito (missing), which I am guessing means it is not really in the repo or the entry in the repo does not work.

This is an added comment about overlooking the obvious - I was mispelling mosquitto (yes, I was trying to install something I typed as mosquito, missing one 't'). It worked much better with the correct spelling and now I can take back most of those things I was saying about the maintainer of the repo.

I notice no activity on these wiki pages for over a year. Anybody actually use this section of the Wiki?

== Proposal: Consolidating Disk Installation Materials ==
It looks like the material on disk-based installation is currently spread between this page and another dedicated page [[Classic install or sys mode on Raspberry Pi|sys-mode install page]]. I would like to propose merging it with the sys-install instructions, so there's only one copy. That will lower the maintenance burden when the procedure changes. --[[User:Etothepii|Etothepii]] June 27, 2021.

== OTG mode on Pi CM4 ==
On Pi Compute Module 4 with I/O board, it seems to be necessary to set: <code>otg_mode=1</code>. This is due to the way it's wired as far as I can tell and the setting is present in stock Raspberry PI OS config file. I've updated the preparation section accordingly.

== Moving content around ==

The way content was sorted on the page was not ideal. First there's preparation steps, followed by installation steps. But along with the first installation steps, there's an explanation that this process will install Alpine in diskless mode and the implications of this. It's not ideal to explain what we're doing halfway through the process.

I've moved this explanation to the top, so that people can understand what they're doing and decide the right process before going through half the steps. Hopefully, this'll result in content in this page being in a more intuitive order.

Please let me know if you have any comments on this. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 14:09, 20 December 2022 (UTC)

== "Note: Raspberry Pi Imager will create ... you may want to grow that partition afterwards" ==

<blockquote>
> 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.
</blockquote>

It's worth pointing out that rpi-imager creates neither a partition nor can you grow it afterwards.

rpi-imager creates this:

<pre>
$ parted -l
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 3965MB
Sector size (logical/physical): 512B/512B
Partition Table: loop
Disk Flags:

Number Start End Size File system Flags
1 0.00B 3965MB 3965MB fat16
</pre>

You can't create a second partition or grow this partition, as it is not a partition. It should be possible to grow the filesystem on the device, but fatresize refuses to do so, as it tries to fix the non-existing partition table:

<pre>
$ sudo fatresize -s 1G -f /dev/sdb1
fatresize 1.1.0 (20250116)
part(start=0, end=7744511, length=7744512)
No Implementation: GNU Parted cannot resize this partition to this size. We're working on it!
$ sudo fatresize -s 1G -f /dev/sdb
fatresize 1.1.0 (20250116)
part(start=0, end=7744511, length=7744512)
No Implementation: GNU Parted cannot resize this partition to this size. We're working on it!
</pre>

So with current versions of rpi-imager at least you really actually can't install Alpine Linux. --[[User:Enkore|Enkore]] ([[User talk:Enkore|talk]]) 15:54, 26 August 2025 (UTC)

== "Note: ... you may want to grow that partition afterwards" ==

<blockquote>
> It's worth pointing out that rpi-imager creates neither a partition nor can you grow it afterwards.
</blockquote>
This may be a bit of an overstatement (ref [[Raspberry_Pi#Resize_partition_created_with_image_file|workaround]], [https://gitlab.alpinelinux.org/alpine/aports/-/issues/17561#note_547712 issue] & [https://gitlab.alpinelinux.org/alpine/aports/-/merge_requests/91195 fix]). 
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 13:50, 11 October 2025 (UTC)

== Useful ERASE_DISKS variable ==
<blockquote>
In most cases the desired installation disk will be the same as the live install media. In most cases setup-disk will prompt asking to install to the install media. In some cases, such as if the install media is not the only disk present, it may be necessary to manually specify it by running:

ERASE_DISKS=/dev/mmcblk0 setup-disk -m sys /dev/mmcblk0
</blockquote>

Thank you for your useful contribution, [[User:Spubby|Spubby]], as this can help users to implement a very useful, fully non-interactive {{ic|setup-disk}} process when using an answerfile for {{ic|setup-alpine}}, confirmed in Issue {{Issue|10549}}. Although this '''Raspberry Pi''' wiki page does not deal with answerfiles, your tip has been reworked into that [[Using_an_answerfile_with_setup-alpine#Answerfile_Variables|answerfile wiki]]! That page has been proposed to [[Talk:Using_an_answerfile_with_setup-alpine| be moved]], notwithstanding. Thanks also for your helpful point earlier about [[WirePlumber]] requiring udev for ALSA device discovery, which now appears in the Prerequisites section! Please continue your help! - [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 08:39, 28 November 2025 (UTC)

== Picam ==
Few comments on this section:
* I added information in <code>usercfg</code> section for camera detection/setup.
* Is <code>udev</code> really required? If is really specific to package (if so, an issue may need to be opened against the package so that a dependency is added)?
* If there are no more specific bugs/workarounds needed with this package, it pretty much is a standard package install procedure, so unsure we should keep that dedicated section overall.
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 11:30, 04 December 2025 (UTC)

Raspberry Pi

2025-12-04T11:29:09Z

Macmpi: /* Customize config.txt and usercfg.txt */ camera detection

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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, 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Test the picam using the command {{Cmd|$ libcamera-hello --list-cameras}}

=== 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]]

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

Talk:Raspberry Pi

2025-12-04T11:05:51Z

Macmpi:

== Known Bugs ==
Added a warning since I wasted more than an hour trying to boot.
-- [[User:Lucid|Lucid]] Thu, 11 Feb 2021 15:01:24 -0500

== Entropy ==

Added a troubleshooting section since I ran into a few issues that weren't immediately obvious. I'll update the section a bit more later but for the entropy issue I haven't yet found a good solution (appropriate package? haveged with runlevel default didn't help) so put in the best short term fix I could find for now.

It might be a good idea to add a note about tmpfs being ram-limited. On a 3A+ only ~200M is available for / on a basic installation which severely limits the amount of packages that can be installed.

== Persistence ==
Wouldn't it be more reasonable to partition the SD-Card accordingly? That way, you could have FS > 2GB, too. --[[User:Kurushiyama|Kurushiyama]] ([[User talk:Kurushiyama|talk]]) 10:53, 8 October 2016 (UTC)

I have read that using a journalling fs is not a good idea for SD cards as it shortens their life by multiplying the read/writes. Wouldn't ext2 thus be a better fs for persistent overlays? -- [[User:Nevarmaor|Nevarmaor]] ([[User talk:Nevarmaor|talk]]) 21:56, 20 February 2017 (UTC)

Having burned holes in far too many SD Cards I'm writing up some notes to setup a persistent storage running off of [https://en.wikipedia.org/wiki/F2FS F2FS]. I think that should be the default.
-- [[User:Lucid|Lucid]] Thu, 11 Feb 2021 15:01:24 -0500

== Installing Alpine- Linux on raspberry pi zero w (udhcpc fail problem) ==

The existing tutorial for raspberry pi is followed except on the reboot, the udhcpc attempts to connect and fails. I managed to fix this problem by editing the /etc/network/interfaces file and add the line:

iface wlan0 inet dhcp
pre-up wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf #<--This is the line added to pre-start the wpa_supplicant daemon and log on correctly.

I learned this with the help of the tutorial by Jack Wallen: How to Configure Wireless... on linux.com website

== Which version should I use? ==

There are now three versions of Alpine to choose from (armv7, armhf, aarch64), it might be useful to have a table indicating which version is supported on which hardware. (I'm already unclear on why armv7 and armhf, I assume both are 32 bits and armv7 has soft-float-point instead of hard-float-point, but don't all RPi devices have hard-float-point capabilities? It would be useful to have a little text about this.)

As I understand aarch64 only applies to BCM2837 and above chips (ARMv8 and above), which means it can only run on RPi 3 and above (but I believe RPi 3 and above should be able to use the other images since they also support the 32 bits mode).

Conversely I assume armhf should be usable on all RPi.

== New Install on RPi Zero W ==

I finally got my Pi Zero W installation done and encountered during setup and subsequent boots very sketchy network performance in the form of very high packet loss. I overcame this by switching from static IP address (which seemed to break networking scripts) to dhcp by editing the /etc/network/interfaces file. I also edited the /etc/wpa_supplicant/wpa_supplicant.conf file using vi to delete duplicated entries which accumulated while trying to get a decent network connection via wireless.

I then went on to try to install the software which is the purpose of using Alpine for me, mosquitto. This had me stumped as I am using armhf, V3.12, have the 3.12 main, community, edge main and community and testing repos and can see mosquito and mosquito-clients packages in the repository listing but consistently get errors on install. I tried to resolve dependencies by hand via installation on required packages with the result I can install some but not all of these packages. I can install other software such as sshd and nmap but get an almost meaningless to me error about unsatisfiable contraints, mosquito (missing), which I am guessing means it is not really in the repo or the entry in the repo does not work.

This is an added comment about overlooking the obvious - I was mispelling mosquitto (yes, I was trying to install something I typed as mosquito, missing one 't'). It worked much better with the correct spelling and now I can take back most of those things I was saying about the maintainer of the repo.

I notice no activity on these wiki pages for over a year. Anybody actually use this section of the Wiki?

== Proposal: Consolidating Disk Installation Materials ==
It looks like the material on disk-based installation is currently spread between this page and another dedicated page [[Classic install or sys mode on Raspberry Pi|sys-mode install page]]. I would like to propose merging it with the sys-install instructions, so there's only one copy. That will lower the maintenance burden when the procedure changes. --[[User:Etothepii|Etothepii]] June 27, 2021.

== OTG mode on Pi CM4 ==
On Pi Compute Module 4 with I/O board, it seems to be necessary to set: <code>otg_mode=1</code>. This is due to the way it's wired as far as I can tell and the setting is present in stock Raspberry PI OS config file. I've updated the preparation section accordingly.

== Moving content around ==

The way content was sorted on the page was not ideal. First there's preparation steps, followed by installation steps. But along with the first installation steps, there's an explanation that this process will install Alpine in diskless mode and the implications of this. It's not ideal to explain what we're doing halfway through the process.

I've moved this explanation to the top, so that people can understand what they're doing and decide the right process before going through half the steps. Hopefully, this'll result in content in this page being in a more intuitive order.

Please let me know if you have any comments on this. [[User:WhyNotHugo|WhyNotHugo]] ([[User talk:WhyNotHugo|talk]]) 14:09, 20 December 2022 (UTC)

== "Note: Raspberry Pi Imager will create ... you may want to grow that partition afterwards" ==

<blockquote>
> 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.
</blockquote>

It's worth pointing out that rpi-imager creates neither a partition nor can you grow it afterwards.

rpi-imager creates this:

<pre>
$ parted -l
Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 3965MB
Sector size (logical/physical): 512B/512B
Partition Table: loop
Disk Flags:

Number Start End Size File system Flags
1 0.00B 3965MB 3965MB fat16
</pre>

You can't create a second partition or grow this partition, as it is not a partition. It should be possible to grow the filesystem on the device, but fatresize refuses to do so, as it tries to fix the non-existing partition table:

<pre>
$ sudo fatresize -s 1G -f /dev/sdb1
fatresize 1.1.0 (20250116)
part(start=0, end=7744511, length=7744512)
No Implementation: GNU Parted cannot resize this partition to this size. We're working on it!
$ sudo fatresize -s 1G -f /dev/sdb
fatresize 1.1.0 (20250116)
part(start=0, end=7744511, length=7744512)
No Implementation: GNU Parted cannot resize this partition to this size. We're working on it!
</pre>

So with current versions of rpi-imager at least you really actually can't install Alpine Linux. --[[User:Enkore|Enkore]] ([[User talk:Enkore|talk]]) 15:54, 26 August 2025 (UTC)

== "Note: ... you may want to grow that partition afterwards" ==

<blockquote>
> It's worth pointing out that rpi-imager creates neither a partition nor can you grow it afterwards.
</blockquote>
This may be a bit of an overstatement (ref [[Raspberry_Pi#Resize_partition_created_with_image_file|workaround]], [https://gitlab.alpinelinux.org/alpine/aports/-/issues/17561#note_547712 issue] & [https://gitlab.alpinelinux.org/alpine/aports/-/merge_requests/91195 fix]). 
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 13:50, 11 October 2025 (UTC)

== Useful ERASE_DISKS variable ==
<blockquote>
In most cases the desired installation disk will be the same as the live install media. In most cases setup-disk will prompt asking to install to the install media. In some cases, such as if the install media is not the only disk present, it may be necessary to manually specify it by running:

ERASE_DISKS=/dev/mmcblk0 setup-disk -m sys /dev/mmcblk0
</blockquote>

Thank you for your useful contribution, [[User:Spubby|Spubby]], as this can help users to implement a very useful, fully non-interactive {{ic|setup-disk}} process when using an answerfile for {{ic|setup-alpine}}, confirmed in Issue {{Issue|10549}}. Although this '''Raspberry Pi''' wiki page does not deal with answerfiles, your tip has been reworked into that [[Using_an_answerfile_with_setup-alpine#Answerfile_Variables|answerfile wiki]]! That page has been proposed to [[Talk:Using_an_answerfile_with_setup-alpine| be moved]], notwithstanding. Thanks also for your helpful point earlier about [[WirePlumber]] requiring udev for ALSA device discovery, which now appears in the Prerequisites section! Please continue your help! - [[User:John3-16|John3-16]] ([[User talk:John3-16|talk]]) 08:39, 28 November 2025 (UTC)

== Picam ==
Few comments on this section:
* Is <code>udev</code> really required? Does that relate to [https://www.raspberrypi.com/documentation/computers/config_txt.html#camera_auto_detect camera_auto_detect] configuration feature (with specific rules probably not available in Alpine's udev packages anyway), or is really specific to package (if so, an issue may need to be opened against the package so that a dependency is added)?
* If there are no more specific bugs/workarounds needed with this package, it pretty much is a standard package install procedure, so unsure we should keep that dedicated section overall.

Raspberry Pi

2025-12-04T10:18:55Z

Macmpi: /* Resize partition created with image file */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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).
* 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== 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]]

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

Raspberry Pi

2025-12-04T08:39:22Z

Macmpi: /* Resize partition created with image file */ simplify from 3.23

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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).
* 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== 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|printf "d\nn\np\n1\n2048\n+127M\nt\n06\nx\nb\n0\nr\nw\n" <nowiki>|</nowiki> doas fdisk /dev/mmcblk0
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]]

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

Raspberry Pi

2025-12-04T08:11:41Z

Macmpi: /* Manual method */ update wording

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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).
* 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-12-04T08:08:30Z

Macmpi: cm0 supported from 3.23

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm0, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm0, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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).
* 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-12-02T07:53:49Z

Macmpi: /* Linux Kernel Graphics Modes */ add reference

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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).
* 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Talk:Using an answerfile with setup-alpine

2025-11-28T17:38:21Z

Macmpi: Created page with "This page content should probably be better linked/referenced with main setup-alpine page. Some content is somehow redundant (sub-setup scripts and help text) and MACRO parameters [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10549 export passing] hint could be explained. Macmpi (talk) 17:35, 28 November 2025 (UTC)"

This page content should probably be better linked/referenced with main [[setup-alpine]] page. 
Some content is somehow redundant (sub-setup scripts and help text) and MACRO parameters [https://gitlab.alpinelinux.org/alpine/alpine-conf/-/issues/10549 export passing] hint could be explained. 
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 17:35, 28 November 2025 (UTC)

User talk:Spubby

2025-11-28T17:12:57Z

Macmpi:

Hi,
Sorry had to revert your change on Pi install, as that note was confusing in this place, and may probably need to be discussed elsewhere (like in [[setup-alpine]] pages, or similar). Once 3.23 is released, <code>setup-disk</code> help text may be added there, and it will explain <code>ERASE_DISKS</code> use for any platform. 
Hope this helps understanding. 
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 17:10, 28 November 2025 (UTC)

User talk:Spubby

2025-11-28T17:11:32Z

Macmpi:

Hi,
Sorry had to revert your change on Pi install, as that note was confusing in this place, and may probably need to be discussed elsewhere (like in [[setup-alpine]] pages). once 3.23 will be released, setup-disk help text may be added there, and it will explain ERASE_DISKS use. 
Hope this helps understanding. 
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 17:10, 28 November 2025 (UTC)

User talk:Spubby

2025-11-28T17:10:56Z

Macmpi:

Hi,
Sorry had to revert your change on Pi install, as that note was confusing in this place, and may probably need to be discussed elsewhere (like in [[setup-alpine]] pages). once 3.23 will be released, setup-disk help text may be added there, and it will explain ERASE_DISKS function. 
Hope this helps understanding. 
[[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 17:10, 28 November 2025 (UTC)

User talk:Spubby

2025-11-28T17:08:49Z

Macmpi: Created page with "Hi, Sorry had to revert your change on Pi install, as that note was confusing in this place, and may probably need to be discussed elsewhere (like in setup-alpine pages). once 3.23 will be released, setup-disk help text may be added there, and it will explain ERASE_DISKS function. Hope this helps understanding."

Raspberry Pi

2025-11-28T17:03:05Z

Macmpi: Undo revision 31556 by Spubby (talk)

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-27T12:39:00Z

Macmpi: /* Installation */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-27T12:04:28Z

Macmpi: new section on serial ports

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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).

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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-27T08:11:19Z

Macmpi: /* Installation */ mention date issue for setup

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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).

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-21T15:24:54Z

Macmpi: /* Fine-tuned support */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-21T15:24:11Z

Macmpi: /* Fine-tuned support */ add Pi-specific package info

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T19:07:19Z

Macmpi: /* Fine-tuned support */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

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

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

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'''.

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T19:02:14Z

Macmpi: /* Fine-tuned support */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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 very [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.

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

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'''.

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T18:59:26Z

Macmpi: /* Fine-tuned support */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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 very [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.

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

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/community/linux-stable 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'''.

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T18:54:16Z

Macmpi: /* Fine-tuned support */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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 very [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.

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

Other available [[Kernels|generic kernels]] like <code>linux-lts</code> are built from upstream with ''Alpine's distro 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'''.

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T18:47:23Z

Macmpi: /* Fine-tuned support */

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== 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 very [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.

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

Other [[Kernels|available kernels]] like <code>linux-lts</code> are built from upstream with ''Alpine's distro 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'''.

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T18:45:40Z

Macmpi: rewording on kernels

{{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
|-
|armv7 || Pi 2, 3, 3+, Zero2W, cm3, cm3+
|-
| aarch64 || Pi 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5
|}

== Fine-tuned support ==

<code>linux-rpi</code> package 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 very [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.

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

Other [[Kernels|available kernels]] like <code>linux-lts</code> are built from upstream with ''Alpine's distro 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'''.

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Include:Arm support matrix

2025-11-05T14:56:59Z

Macmpi: armhf is Pi only (link there)

<noinclude>
{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| colspan="4" |Alpine Linux Hardware Support Matrix
|-
! Architecture !! Port !! Description !! Since</noinclude>
|-
| rowspan="3" |[[:Category:ARM|ARM]] || [[Raspberry Pi|armhf]] || 32 bit ARM with hard-float ABI - for ARMv6 devices - [[Raspberry Pi]] 1, Zero, ZeroW, cm1 (''defconfig bcmrpi'') || v3.0
|-
| | [[Alpine on ARM|armv7]] || 32 bit ARM - for ARMv7 devices (including [[Raspberry Pi]] 2, 3, 3+, Zero2W, cm3, cm3+ with ''defconfig bcm2709'') || v3.9
|-
| | [[Alpine on ARM|aarch64]] || 64 bit ARM - for ARMv8+ devices (including [[Raspberry Pi]] 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5 with ''defconfig bcm2711'') || v3.5
<noinclude>|}</noinclude>

Talk:Include:Arm support matrix

2025-11-05T14:47:43Z

Macmpi:

In fact this matrix mixes 2 dimensions (hardware and kernel builds) which may be a bit confusing from non-Pi ARM users. 
Indeed armv7/aarch64 hardware is supported by several kernels: generic upstream (linux-lts/linux-stable) like for all other hardware platforms, and custom Pi (linux-rpi with Pi foundation downstream patches and defconfigs). For armhf it's only Pi. 
The matrix as it stands may lead to think ARM is for Pi only, which it is not. 
Maybe we should have 2 different matrices: one only on HW for main page (just CPU cores, not talking about defconfigs), and another one on Pi Page that dives into the Pi specific models and defconfigs. 
Thoughts (made few tweaks to hopefully clarify)? [[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 14:48, 05 November 2025 (UTC)

Include:Arm support matrix

2025-11-05T14:45:21Z

Macmpi:

<noinclude>
{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| colspan="4" |Alpine Linux Hardware Support Matrix
|-
! Architecture !! Port !! Description !! Since</noinclude>
|-
| rowspan="3" |[[:Category:ARM|ARM]] || [[Alpine on ARM|armhf]] || 32 bit ARM with hard-float ABI - for ARMv6 devices - [[Raspberry Pi]] 1, Zero, ZeroW, cm1 (''defconfig bcmrpi'') || v3.0
|-
| | [[Alpine on ARM|armv7]] || 32 bit ARM - for ARMv7 devices (including [[Raspberry Pi]] 2, 3, 3+, Zero2W, cm3, cm3+ with ''defconfig bcm2709'') || v3.9
|-
| | [[Alpine on ARM|aarch64]] || 64 bit ARM - for ARMv8+ devices (including [[Raspberry Pi]] 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5 with ''defconfig bcm2711'') || v3.5
<noinclude>|}</noinclude>

Include:Arm support matrix

2025-11-05T14:42:30Z

Macmpi: armv7/aarch64 not Pi only & link Raspberry Pi page

<noinclude>
{|class="wikitable" align="center" style="width:100%; border:1px #0771a6 solid; background:#f9f9f9; text-align:left; border-collapse:collapse;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| colspan="4" |Alpine Linux Hardware Support Matrix
|-
! Architecture !! Port !! Description !! Since</noinclude>
|-
| rowspan="3" |[[:Category:ARM|ARM]] || [[Alpine on ARM|armhf]] || 32 bit ARM with hard-float ABI - for ARMv6 devices - [[Raspberry Pi]] 1, Zero, ZeroW, cm1 (defconfig bcmrpi) || v3.0
|-
| | [[Alpine on ARM|armv7]] || 32 bit ARM - for ARMv7 devices - including [[Raspberry Pi]] 2, 3, 3+, Zero2W, cm3, cm3+ (defconfig bcm2709) || v3.9
|-
| | [[Alpine on ARM|aarch64]] || 64 bit ARM - for ARMv8+ devices - including [[Raspberry Pi]] 3, 3+, 4, 400, Zero2W, cm3, cm3+, cm4, 5, 500, 500+, cm5 (defconfig bcm2711) || v3.5
<noinclude>|}</noinclude>

Talk:Include:Arm support matrix

2025-11-05T14:25:11Z

Macmpi: ARM hardware matrix issue

In fact this matrix mixes 2 dimensions (hardware and kernel builds) which may be a bit confusing from non-Pi ARM users. 
Indeed armv7/aarch64 hardware is supported by several kernels: generic upstream (linux-lts/linux-stable) like for all other hardware platforms, and custom Pi (linux-rpi with Pi foundation downstream patches and defconfigs). For armhf it's only Pi. 
The matrix as it stands may lead to think ARM is for Pi only, which it is not. 
Maybe we should have 2 different matrices: one only on HW for main page (just CPU cores, not talking about defconfigs), and another one on Pi Page that dives into the Pi specific models and defconfigs. 
Thoughts? [[User:Macmpi|Macmpi]] ([[User talk:Macmpi|talk]]) 14:25, 05 November 2025 (UTC)

Raspberry Pi

2025-11-05T13:41:48Z

Macmpi: /* Compatibility list */ add links for firmware source repo

{{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;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| colspan="4" |Alpine Linux Hardware Support Matrix
|-
! Architecture !! Port !! Description !! Since
|-
{{:Include:Arm support matrix}}
|}

{{Note|
* <code>linux-rpi</code> kernels are built with ''Pi Foundation's downstream patches and defconfigs'' files (with very [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/main/linux-rpi/common-changes.config minor deviations]): therefore user should expect mostly same features than with PiOS shipped kernels. <code>linux-rpi</code> are the ''supported kernels'' shipped within Alpine's ''Raspberrypi install releases''.
* <code>linux-firmware</code> bundles <code>linux-firmware-brcm</code> 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).
* <code>linux-lts</code> and <code>linux-stable</code> kernels are upstream kernels only with ''Alpine's distro 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 features, and may require different/additional configurations steps (''unsupported'').}}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T13:33:56Z

Macmpi: /* Compatibility list */ shipping brcm firmware files

{{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;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| colspan="4" |Alpine Linux Hardware Support Matrix
|-
! Architecture !! Port !! Description !! Since
|-
{{:Include:Arm support matrix}}
|}

{{Note|
* <code>linux-rpi</code> kernels are built with ''Pi Foundation's downstream patches and defconfigs'' files (with very [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/main/linux-rpi/common-changes.config minor deviations]): therefore user should expect mostly same features than with PiOS shipped kernels. <code>linux-rpi</code> are the ''supported kernels'' shipped within Alpine's ''Raspberrypi install releases''.
* <code>linux-firmware</code> bundles <code>linux-firmware-brcm</code> containing ''downtream Pi Foundation's'' shipping wifi and bluetooth firmware files for Pi devices: it ensures optimal support for wireless connectivity (on par with PiOS community).
* <code>linux-lts</code> and <code>linux-stable</code> kernels are upstream kernels only with ''Alpine's distro 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 features, and may require different/additional configurations steps (''unsupported'').}}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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

Raspberry Pi

2025-11-05T12:30:16Z

Macmpi: /* Compatibility list */

{{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;"
|- style="background:#333333; color:#ffffff; font-size: 1.2em; text-align:center;"
| colspan="4" |Alpine Linux Hardware Support Matrix
|-
! Architecture !! Port !! Description !! Since
|-
{{:Include:Arm support matrix}}
|}

{{Note|<code>linux-rpi</code> kernels are built with ''Pi Foundation's downstream patches and defconfigs'' files (with very [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/main/linux-rpi/common-changes.config minor deviations]): therefore user should expect mostly same features than with PiOS shipped kernels. <code>linux-rpi</code> are the ''supported kernels'' shipped within Alpine's ''Raspberrypi install releases''. 
<code>linux-lts</code> and <code>linux-stable</code> kernels are upstream kernels only with ''Alpine's distro generic defconfigs'': they may be used with any <code>armv7</code> or <code>aarch64</code> devices, including related Pi devices. However, they may not fully support all expected features, and may require different/additional configurations steps.}}

== 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.}}
# 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 volume with only about [https://gitlab.alpinelinux.org/alpine/aports/-/blob/98f4e18d0ab978e3a6dd6fad23cbbd4464a5cdc8/scripts/mkimg.arm.sh#L56 8MB of free space]. 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.

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]]).
* Enabling default serial console with <code>enable_uart=1</code>, together with <code>console=serial0,115200</code> 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 {{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).
* 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 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/2788cb549a19bf2e77901c4071ef88c2ad683b7c 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...

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.}}

=== Picam ===

{{Note| The below instructions has been tested only in [[Classic install or sys mode on Raspberry Pi|sys mode]] install with Pi Zero 2W.}}

# To use {{pkg|rpicam-apps|arch=}} package, upgrade to [[Repositories#Upgrading_to_edge|edge]] branch.
# Setup eudev as device manager:{{Cmd|# setup-devd udev}}
# Add <Code>camera_auto_detect=1</Code> option to the user config file {{Path|/boot/usercfg.txt}}
# Install the package {{pkg|rpicam-apps|arch=}} available in the [[Repositories#Testing|testing]] repository.
# Due to bug {{Issue|16911}}, change the permission after every reboot as follows:{{Cmd|$ doas chmod 666 /dev/dma_heap/*}}
# Test the picam by the command {{Cmd|$ libcamera-hello --list-cameras}}

=== Resize partition created with image file ===
Media created from image file (manually or with [[#Raspberry Pi Imager|Raspberry Pi Imager]]) can '''cautiously''' be grown up to 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. 
For exemple scripting it (128MB size):
{{Cmd|doas fdisk /dev/sda <<EOF
d
n
p
1
2048
+127M
t
06
x
b
0
r
w
EOF
doas fatresize -n 1 -s 128M /dev/sda}}

== 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]]

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