Jump to content

NixOS on ARM/Raspberry Pi 5: Difference between revisions

From Official NixOS Wiki
← Older edit
JamieMagee (talk | contribs)
5 edits
VisualWikitext
m Fix typos
Document nixos-unstable image support for the Pi 5 family, NVMe boot limits, serial setup, power and cooling, and the archived UEFI port
 
(29 intermediate revisions by 11 users not shown)
Line 1: Line 1:
{{ARM/breadcrumb}}
{{ARM/breadcrumb}}
<div class="infobox">
<div class="infobox">
{|class="table"
{| class="table"
!colspan="2" class="title"|Raspberry Pi 5 Family
! colspan="2" class="title" | Raspberry Pi 5 family
|-
|-
|colspan="2"|[[File:Raspberry_Pi_5,_8_GB_RAM.jpg|frameless|256px|A Raspberry Pi 5.]]
| colspan="2" | [[File:Raspberry_Pi_5,_8_GB_RAM.jpg|frameless|256px|A Raspberry Pi 5.]]
|-
|-
!Manufacturer
! Manufacturer
|Raspberry Pi Foundation
| Raspberry Pi Ltd
|-
|-
!Architecture
! Architecture
|AArch64
| AArch64
|-
|-
!Bootloader
! Stock boot method
|Custom or UEFI
| Raspberry Pi EEPROM and firmware, U-Boot, and extlinux from microSD
|-
|-
!Boot order
! SoC
|Configurable; SD, USB, Netboot
| BCM2712
|-
|-
!Maintainer
! Variants
|leo60228
| Pi 5, Pi 500, Pi 500+, CM5, and CM5 Lite
|-
!colspan="2" class="title"|Raspberry Pi 5B
|-
!SoC
|BCM2712
|}
|}
</div>
</div>
The Raspberry Pi family of devices is a series of single-board computers made by the Raspberry Pi Foundation. They are all based on Broadcom System-on-a-chip (SoCs).


== Status ==
The generic AArch64 SD image on <code>nixos-unstable</code> supports the '''Raspberry Pi 5''', Raspberry Pi 500, Raspberry Pi 500+, Compute Module 5, and Compute Module 5 Lite. NixOS 26.05 images do not include the required Pi 5-family boot files, so use an image from <code>nixos-unstable</code>.<ref name="pi5-image">[https://github.com/NixOS/nixpkgs/pull/537862 nixpkgs PR #537862: sd-image-aarch64: support rpi5]</ref> The stock image boots from microSD through Raspberry Pi firmware, U-Boot, and extlinux.


== Installation ==


Use the unstable generic AArch64 SD image described on the [[NixOS on ARM/Raspberry Pi#Installation|family page]]. The image contains the device trees used by Raspberry Pi 5, Raspberry Pi 500, Raspberry Pi 500+, Compute Module 5, and Compute Module 5 Lite, together with a single 64-bit U-Boot binary for Raspberry Pi boards.<ref name="generic-image">[https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/installer/sd-card/sd-image-aarch64.nix Nixpkgs generic AArch64 SD image module]</ref> Raspberry Pi 500 and Raspberry Pi 500+ share board type <code>0x19</code>, for which U-Boot selects <code>bcm2712-rpi-500.dtb</code>.<ref name="revision-codes">[https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#new-style-revision-codes Raspberry Pi revision codes]</ref><ref name="uboot-models">[https://github.com/u-boot/u-boot/blob/v2026.07/board/raspberrypi/rpi/rpi.c U-Boot v2026.07 Raspberry Pi model table]</ref> In a flake, import <code>nixos-hardware.nixosModules.raspberry-pi-5</code>. With channels, import <code>&lt;nixos-hardware/raspberry-pi/5&gt;</code>. The family page explains that a profile does not create an image or stage U-Boot.


'''Support for the Raspberry Pi 5 is currently downstream and experimental'''.
== Kernel and hardware defaults ==
It will not be fully supported until mature support exists in the upstream Linux kernel and
the [https://github.com/u-boot/u-boot U-Boot] boot loader, but using an '''UEFI bootloader already provides a workable solution'''.


The Raspberry Pi 5's boot process follows the [https://youtu.be/UvFG76qM6co?si=e9O1s9mS3wpIpEl9&t=308 typical boot stages on embedded devices], some of which have to be adapted to work with NixOS. For that it's helpful to understand more about the stages:
The profile selects a pinned kernel from Raspberry Pi's downstream Linux tree and limits device trees to BCM2712 Raspberry Pi boards. Its initrd includes NVMe, BCM2712 PCIe, RP1 clock, and support for the RP1 multifunction device. It disables GRUB and enables extlinux generation.<ref name="profile">[https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/5/default.nix nixos-hardware Raspberry Pi 5 profile]</ref>


1. '''ROM boot loader''': The first-stage boot loader comes "burned in" on the Pi in a tiny
See [[NixOS on ARM/Raspberry Pi#Board profiles|Board profiles]] for Wi-Fi firmware requirements on custom systems.
[https://de.wikipedia.org/wiki/One_Time_Programmable One-Time-Programmable memory (OTP)]
so it cannot be changed anymore. It's '''only able to load the next second-stage boot loader below''', and reset it in case you have messed up.


See the [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#first-stage-bootloader official documentation].
=== Graphics ===


Nothing to adapt here.
The shared profile defaults request full VC4 KMS. For Xorg, the Pi 5 profile marks the VC4 modesetting device as the primary GPU. This configuration has not been tested with RP1-connected DPI, composite, or MIPI DSI displays.<ref name="profile" /> HDMI and other VC4 display configurations use <code>vc4-kms-v3d</code>. They do not require <code>vc4-kms-v3d-pi5</code>.


== Storage ==


2. '''EEPROM boot loader''': The second-stage boot loader comes built-in on the Pi in a bit larger, rewriteable
The Pi 5 profile prepares Linux and the initrd to use PCIe and NVMe. This allows a system to load U-Boot, the kernel, and the initrd from microSD, then mount its root filesystem from NVMe.
[[wikipedia:EEPROM|EEPROM]] memory
'''This loader is also very limited is only able to search for and start yet another, third-stage boot loader from other '''
storage hardware like an SD card, an NVME SSD''', an USB disk, or from the network.'''


This loader (as many other second-stage boot loaders of other devices) is so size-constraint that it only contains
This Linux support does not mean that released U-Boot can load the NixOS boot files from NVMe. In U-Boot v2026.07, <code>rpi_arm64_defconfig</code> enables PCIe enumeration but does not set <code>CONFIG_NVME_PCI</code> or run <code>nvme scan</code>.<ref name="uboot-config">[https://github.com/u-boot/u-boot/blob/v2026.07/configs/rpi_arm64_defconfig U-Boot v2026.07 rpi_arm64_defconfig]</ref> Its NVMe driver also lacks the PCIe inbound DMA address translation required on Pi 5. A July 2026 patch series proposes those changes, but they are not part of v2026.07.<ref name="nvme-series">[https://lists.denx.de/pipermail/u-boot/2026-July/624063.html U-Boot patch series: Fix NVMe, not only on Raspberry Pi 5]</ref>
the bare mimum code to be able to read from an FAT formatted partition. That's why you see and want a separate small
<code>/boot</code> partition on your SD card or SSD that is formatted "FAT" or "VFAT", while your main data is stored on a second
"rootfs" or <code>/</code> partition with fancy, newer partition types like "ext4", "ZFS" or "btrfs".


See the [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#second-stage-bootloader official documentation].
The Pi EEPROM can discover NVMe media and may load <code>u-boot.bin</code> from it. Released U-Boot cannot then continue the normal extlinux flow from that device. Updating only the EEPROM does not remove this limitation. The stock U-Boot v2026.07 chain therefore does not support complete NVMe boot.


See [https://github.com/raspberrypi/rpi-eeprom/releases EEPROM image releases] for improved and wider hardware support.
== Serial console ==
This boot loader can be updated via the <code>rpi-eeprom-update</code> terminal tool
(also [https://search.nixos.org/packages?channel=unstable&type=packages&query=raspberrypi-eeprom available in Nixpkgs])
and loads the binary images (the <code>firmware-2712/pieeprom-*.bin</code> files) from the
[https://github.com/raspberrypi/rpi-eeprom/tree/master/firmware-2712 rpi-eeprom Github project].


Nothing to adapt here yet. However, there's a
Pi 5 exposes its primary UART through the dedicated debug connector. Linux names the hardware device <code>/dev/ttyAMA10</code>, and <code>/dev/serial0</code> points to it.<ref name="uart">[https://www.raspberrypi.com/documentation/computers/configuration.html#configure-uarts Raspberry Pi UART documentation]</ref>
[https://github.com/raspberrypi/firmware/issues/1857 feature request to support smaller
third-stage boot loaders in this second-stage].


3. '''Firmware boot loader''': The third-stage boot loader is loaded from the first partition (usually called <code>/boot</code>)
The profile sets <code>enable_uart=0</code> for Pi 5 to prevent ghost UART input from interrupting U-Boot on affected boards.<ref name="config-defaults">[https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/common/config-txt-defaults.nix nixos-hardware Raspberry Pi config.txt defaults]</ref> This example enables a serial console:
of an SD card, NVME SSD or other storage hardware described above.
Because '''size is usually not an issue here anymore so you can have large, fully-fledged boot loaders''' like
[https://www.freedesktop.org/software/systemd/man/latest/systemd-boot.html systemd-boot] (default with NixOS; requires UEFI), or full
[https://github.com/u-boot/u-boot U-Boot] (popular with embedded devices like the Pi) or
[https://www.gnu.org/software/grub/ GRUB] (generally popular with Linux Distros).


However, '''the standard Pi 5 setup has no third-stage boot loader'''.  
<syntaxhighlight lang="nix">
The second stage EEPROM boot loader loads the firmware (code to control other hardware on the Pi 5; [https://en.wikipedia.org/wiki/Devicetree device tree
{ lib, ... }:
files] in compact binary format <code>*.dtb</code>), some settings (<code>cmdline.txt</code> on which partition to find the rest of the system;
{
<code>config.txt</code> for general boot settings),
  hardware.raspberry-pi.configtxt.settings.pi5.enable_uart = lib.mkForce true;
and directly the Linux kernel from a <code>/boot/firmware/</code> folder. On the Pi 5's default Debian image this is
  boot.kernelParams = [ "console=ttyAMA10,115200n8" ];
the <code>kernel2712.img</code> (specialized, more-performant kernel
}
named after the Pi 5's Brodcom BCM2712 ARMv8 SoC chip) or as a fallback the <code>kernel8.img</code> (generic, slower ARMv8 kernel for the Pi 4 that
</syntaxhighlight>
also works for Pi 5) that you find on the [https://github.com/raspberrypi/firmware/tree/master/boot Pi Firmware Github project].
 
See the [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#differences-on-raspberry-pi-5 official documentation].
 
'''Adaptations for booting NixOS''':


In order to boot NixOS with it's default boot loader systemd-boot we need UEFI support, so replace the
Test U-Boot interaction after enabling the UART, and use a 3.3 V adapter designed for the Pi 5 debug connector.
  1. ROM -> 2. EEPROM -> Kernel -> NixOS
workflow with third-stage and fourth-stage boot loaders (both as firmware on an SD card or NVME SSD etc.)
  1. ROM -> 2. EEPROM -> 3. EDK2 (UEFI boot loader) -> 4. systemd-boot -> Kernel -> NixOS
as follows:


1. '''Install EDK2''':
== Power and cooling ==


We need the first partition of the SD card (or NVME SSD, etc.) again to be formatted as FAT
Raspberry Pi recommends its 27 W USB-C supply for Pi 5. A 5 V, 3 A supply can boot the board, but it reduces the current available to USB devices and fan peripherals. Without a heatsink or fan, the Pi 5 may thermally throttle under sustained load.<ref name="power">[https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply Raspberry Pi power-supply documentation]</ref>
but labelled <code>ESP</code> (EFI System Partition) to conform to (U)EFI standards.
Into this partition we need to place the EDK2 boot loader file <code>RPI_EFI.fd</code>
and a <code>config.txt</code> file with a line <code>armstub=RPI_EFI.fd</code>
which instructs the EEPROM boot loader to load our EDK2 boot loader instead.


See the [https://github.com/worproject/rpi5-uefi EDK2 for Pi 5 Github project]; the releases already contain both of these files.
== Alternative implementation ==


See a [https://github.com/NixOS/nixpkgs/issues/260754#issuecomment-1908664693 guide on how to setup partitions and these files].
The [[NixOS on ARM/Raspberry Pi#Alternative implementations|family page]] describes the [https://github.com/nvmd/nixos-raspberrypi nvmd/nixos-raspberrypi] flake. Its module names and <code>boot.loader.raspberry-pi</code> options are not Nixpkgs or <code>nixos-hardware</code> APIs.


2. '''Install systemd-boot, kernel and NixOS''':
== UEFI ==


The rest is usual NixOS installation on a second partition with the caveat to '''select a Linux kernel that supports the Pi 5''';
The [https://github.com/worproject/rpi5-uefi worproject/rpi5-uefi] EDK2 port is an advanced alternative to U-Boot. The project was archived in February 2025 and is no longer maintained. Its support notice says that the final release was tested on early BCM2712C1 boards and reports problems with D0 boards and newer EEPROM firmware. It is therefore not the default Pi 5 installation path. For experiments, follow the archived project's limitations and the [[NixOS on ARM/UEFI|general ARM UEFI instructions]].
a suitable kernel can be created using [https://gitlab.com/vriska/nix-rpi5/-/blob/main/linux-rpi.nix leo60228's flake] until
that [https://github.com/NixOS/nixpkgs/pull/284391 Pi 5 compatible Linux kernel is available in Nixos-hardware].


Follow [https://github.com/NixOS/nixpkgs/issues/260754#issuecomment-1936211154 this guide] to build
== See also ==
a NixOS system closure that you can install manually onto the Pi with a <code>nixos-install</code> call.
That install tool will install the systemd-boot loader at <code>/boot/EFI/systemd/systemd-bootaa64.efi</code>
and the kernel files at <code>/boot/EFI/nixos/*.efi</code> onto your first ESP partition
and the rest of the NixOS system into your second partition.


Note that building that NixOS system closure has to happen natively, e.g. on a similar aarch64/Arm64 system like newer Macs (fast), or with
* [[NixOS on ARM/Raspberry Pi]]
the [https://docs.kernel.org/admin-guide/binfmt-misc.html binfmt] kernel feature
* [[NixOS on ARM/Installation]]
(enabled with setting <code>boot.binfmt.emulatedSystems = [ "aarch64-linux" ];</code>) using QEMU virtualization
* [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#nvme-ssd-boot Raspberry Pi NVMe documentation]
on any NixOS computer(veeeeerry slow) 


Missing:
== References ==


# How to do faster cross-compilation without binfmt.
<references />
# How to create a convenient SD card image to not install anything manually.
# How to install U-Boot instead of EDK2 and systemd-boot.


=== GPU ===
[[Category:NixOS on ARM]]
For the GPU drivers to work, <code>dtoverlay=vc4-kms-v3d-pi5</code> must be added to <code>/boot/config.txt</code>, and the vendor kernel must currently be used. Only Wayland-based compositors are supported. Note that Xwayland applications may produce broken graphics on KDE; the root cause of this issue has not yet been evaluated.
 
== Board-specific installation notes ==
 
First, install EDK2, following the [https://github.com/worproject/rpi5-uefi#getting-started instructions from the port README]. With EDK2 installed as the Platform Firmware, you can follow the [[NixOS_on_ARM/UEFI|standard instructions for UEFI on ARM]].
 
EDK2 enables booting a mainline kernel, but hardware support will be very limited. Notably, you'll need to perform the installation using Wi-Fi, as Ethernet is unsupported. Once the system is installed, you can switch to the vendor's modified kernel. This is not (yet?) available in Nixpkgs, so you'll need to get it from [https://gitlab.com/vriska/nix-rpi5 a flake]. If you're not using flakes, you can simply add this to your configuration:
 
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
  boot.kernelPackages = (import (builtins.fetchTarball https://gitlab.com/vriska/nix-rpi5/-/archive/main.tar.gz)).legacyPackages.aarch64-linux.linuxPackages_rpi5;
}
</nowiki>}}
 
For the vendor kernel to boot properly, you must switch from ACPI to Device Tree in the UEFI settings (at Device Manager -> Raspberry Pi Configuration -> ACPI / Device Tree -> System Table Mode). When using the vendor kernel (which provides full power management support), you may additionally wish to remove <code>force_turbo=1</code> from <code>/boot/config.txt</code>.
 
If you are using nixos-unstable, then you can also use the rpi4 kernel (this is supposed to be a generic aarch64 kernel for rpi 3,4,5). Although, due to a smaller page size, this will have slightly worse performance:
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
  boot.kernelPackages = pkgs.linuxPackages_rpi4;
}
</nowiki>}}
 
=== Bluetooth ===
If your bluetooth doesn't show up, and you are getting errors in dmesg regarding the serial port at 107050c00, add the following to your nixos configuration:{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{
  boot.kernelParams = [ "8250.nr_uarts=11" "console=ttyAMA10,9600" "console=tty0"];
}
</nowiki>}}

Latest revision as of 17:18, 18 July 2026

Raspberry Pi 5 family
A Raspberry Pi 5.
Manufacturer Raspberry Pi Ltd
Architecture AArch64
Stock boot method Raspberry Pi EEPROM and firmware, U-Boot, and extlinux from microSD
SoC BCM2712
Variants Pi 5, Pi 500, Pi 500+, CM5, and CM5 Lite

The generic AArch64 SD image on nixos-unstable supports the Raspberry Pi 5, Raspberry Pi 500, Raspberry Pi 500+, Compute Module 5, and Compute Module 5 Lite. NixOS 26.05 images do not include the required Pi 5-family boot files, so use an image from nixos-unstable.[1] The stock image boots from microSD through Raspberry Pi firmware, U-Boot, and extlinux.

Installation

Use the unstable generic AArch64 SD image described on the family page. The image contains the device trees used by Raspberry Pi 5, Raspberry Pi 500, Raspberry Pi 500+, Compute Module 5, and Compute Module 5 Lite, together with a single 64-bit U-Boot binary for Raspberry Pi boards.[2] Raspberry Pi 500 and Raspberry Pi 500+ share board type 0x19, for which U-Boot selects bcm2712-rpi-500.dtb.[3][4] In a flake, import nixos-hardware.nixosModules.raspberry-pi-5. With channels, import <nixos-hardware/raspberry-pi/5>. The family page explains that a profile does not create an image or stage U-Boot.

Kernel and hardware defaults

The profile selects a pinned kernel from Raspberry Pi's downstream Linux tree and limits device trees to BCM2712 Raspberry Pi boards. Its initrd includes NVMe, BCM2712 PCIe, RP1 clock, and support for the RP1 multifunction device. It disables GRUB and enables extlinux generation.[5]

See Board profiles for Wi-Fi firmware requirements on custom systems.

Graphics

The shared profile defaults request full VC4 KMS. For Xorg, the Pi 5 profile marks the VC4 modesetting device as the primary GPU. This configuration has not been tested with RP1-connected DPI, composite, or MIPI DSI displays.[5] HDMI and other VC4 display configurations use vc4-kms-v3d. They do not require vc4-kms-v3d-pi5.

Storage

The Pi 5 profile prepares Linux and the initrd to use PCIe and NVMe. This allows a system to load U-Boot, the kernel, and the initrd from microSD, then mount its root filesystem from NVMe.

This Linux support does not mean that released U-Boot can load the NixOS boot files from NVMe. In U-Boot v2026.07, rpi_arm64_defconfig enables PCIe enumeration but does not set CONFIG_NVME_PCI or run nvme scan.[6] Its NVMe driver also lacks the PCIe inbound DMA address translation required on Pi 5. A July 2026 patch series proposes those changes, but they are not part of v2026.07.[7]

The Pi EEPROM can discover NVMe media and may load u-boot.bin from it. Released U-Boot cannot then continue the normal extlinux flow from that device. Updating only the EEPROM does not remove this limitation. The stock U-Boot v2026.07 chain therefore does not support complete NVMe boot.

Serial console

Pi 5 exposes its primary UART through the dedicated debug connector. Linux names the hardware device /dev/ttyAMA10, and /dev/serial0 points to it.[8]

The profile sets enable_uart=0 for Pi 5 to prevent ghost UART input from interrupting U-Boot on affected boards.[9] This example enables a serial console: 

{ lib, ... }:
{
  hardware.raspberry-pi.configtxt.settings.pi5.enable_uart = lib.mkForce true;
  boot.kernelParams = [ "console=ttyAMA10,115200n8" ];
}

Test U-Boot interaction after enabling the UART, and use a 3.3 V adapter designed for the Pi 5 debug connector.

Power and cooling

Raspberry Pi recommends its 27 W USB-C supply for Pi 5. A 5 V, 3 A supply can boot the board, but it reduces the current available to USB devices and fan peripherals. Without a heatsink or fan, the Pi 5 may thermally throttle under sustained load.[10]

Alternative implementation

The family page describes the nvmd/nixos-raspberrypi flake. Its module names and boot.loader.raspberry-pi options are not Nixpkgs or nixos-hardware APIs.

UEFI

The worproject/rpi5-uefi EDK2 port is an advanced alternative to U-Boot. The project was archived in February 2025 and is no longer maintained. Its support notice says that the final release was tested on early BCM2712C1 boards and reports problems with D0 boards and newer EEPROM firmware. It is therefore not the default Pi 5 installation path. For experiments, follow the archived project's limitations and the general ARM UEFI instructions.

See also

References

  1. ↑ nixpkgs PR #537862: sd-image-aarch64: support rpi5
  2. ↑ Nixpkgs generic AArch64 SD image module
  3. ↑ Raspberry Pi revision codes
  4. ↑ U-Boot v2026.07 Raspberry Pi model table
  5. ↑ 5.0 5.1 nixos-hardware Raspberry Pi 5 profile
  6. ↑ U-Boot v2026.07 rpi_arm64_defconfig
  7. ↑ U-Boot patch series: Fix NVMe, not only on Raspberry Pi 5
  8. ↑ Raspberry Pi UART documentation
  9. ↑ nixos-hardware Raspberry Pi config.txt defaults
  10. ↑ Raspberry Pi power-supply documentation
Retrieved from "https://wiki.nixos.org/w/index.php?title=NixOS_on_ARM/Raspberry_Pi_5&oldid=33754"