Official NixOS Wiki

NixOS on ARM/Raspberry Pi 5

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.

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

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"