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 typo
Document nixos-unstable image support for the Pi 5 family, NVMe boot limits, serial setup, power and cooling, and the archived UEFI port
 
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, UEFI or u-boot
| 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).
== Current Status ==
NixOS is not officially supported on the Raspberry Pi 5, and the community efforts to bring the operating system to the development board have been less successful than the ones targeting the previous generation, the [[NixOS on ARM/Raspberry Pi 4|Raspberry Pi 4]]. It is advisable, for the time being, that all critical projects continue using and deploying the older model, for which the support is significantly more robust.
For the adventurous, there are multiple community efforts enabling NixOS on the board, with various degrees of user friendliness, support availability or robustness, some of which can be found in the ''Other solutions'' section below. Amongst them, the community has flagged one repository that seems to have achieved a reasonable trade-off between all the necessary requirements for such a project; this is described in the ''Proposed Solution'' section below. While by no means official, and its level of support still under development, it is a good enough starting ground for people wanting to take advantage of their Raspberry Pi 5.
However, this solution reuses proprietary software distributed by the Raspberry Pi Foundation; which is highly criticized by the NixOS community, and the Linux community at large, for reasons including reproducibility, transparency, security, predictibility, etc. There are efforts in the community to address these issues as well, and the following sub-section is an overview into these efforts.
=== Generic UEFI boot support ===
NixOS doesn't run out-of-box, but relies on several tweaks on the boot process that are maintained by different individuals and spread over multiple repositories. The Raspberry Pi 5's boot process follows the [https://youtu.be/UvFG76qM6co?t=308 typical boot stages on embedded devices], and has the following boot loader steps by default:{{caption|align=center|{{mermaid|flowchart LR|
  ROM --> EEPROM
  EEPROM --> FK[Firmware / Kernel]
  FK --> OS[Raspberry Pi OS]
}}|The normal boot process of a Raspberry Pi 5|alt=A flowchart showing 4 boxes with text in each, one leading to another. In the first box, ROM. In the second, EEPROM. In the third, Firmware / Kernel. In the fourth, Raspberry Pi OS.}}
The pain points for NixOS support are the Pi's [https://github.com/raspberrypi/rpi-eeprom custom EEPROM boot bootloader], its [https://github.com/raspberrypi/firmware proprietary, closed-source firmware] (code to use to hardware components) and [https://github.com/raspberrypi/linux its separately maintained Linux kernel], all of which we would need to update, build and test constantly and separately from the other NixOS Linux kernel variations, which is a large, unmaintainable burden for the NixOS community when the Pi 5 is not the only supported SoC.
The more sustainable goal would be to move towards UEFI support, which would mimic how desktop computers boot into the NixOS operating system, thus minimising the amount of bespoke maintenance needed for the development board. This is what this process would look like:
{{caption|align=center|{{mermaid|flowchart LR|
  ROM --> EEPROM
  EEPROM --> UEFI[UEFI Bootloader]
  UEFI --> SD[Systemd Bootloader]
  SD --> LK[Generic Linux Kernel]
  LK --> OS[Raspberry Pi OS]
}}|The ideal Raspberry Pi 5 boot process|alt=A flowchart containing 5 boxes with text. In this order, each box contains the following: ROM, EEPROM, UEFI Bootloader, Systemd Bootloader, Generic Linux Kernel, and NixOS.}}
The ROM and EEPROM can't be modified, as they are built into the hardware on the development board. However, [https://de.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface UEFI] is also used for booting normal Intel/AMD computers, and the [https://www.freedesktop.org/software/systemd/man/latest/systemd-boot.html systemd-boot] boot loader is THE software that allows us to have and select from multiple NixOS generations on boot (and perform rollbacks if we messed up). Further details about the steps involved in achieving this can be found in the ''Other Solutions'' section, under ''Generic UEFI Boot.''
Finally, there should also be [https://github.com/u-boot/u-boot U-Boot] support soon, as most development boards are widely supported by the project. In that case, the boot process would look like:
{{caption|align=center|{{mermaid|flowchart LR|
  ROM --> EEPROM
  EEPROM --> FK[Firmware / Kernel]
  FK --> U[U-Boot Bootloader]
  U --> OS[Raspberry Pi OS]
}}|Theoretical Raspberry Pi 5 U-Boot boot process|alt=A flowchart showing 5 boxes containing text. In this order, each box contains the following text: ROM, EEPROM, Firmware or Kernel, U-Boot, and NixOS.}}


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.


== Proposed Solution ==
== Installation ==
There is a repository aiming to develop a declarative way of defining Raspberry Pi setups, including, but not limited to, the Raspberry Pi 5. The project is called [https://github.com/nvmd/nixos-raspberrypi?tab=readme-ov-file nixos-raspberrypi], and so far seems to be successful at achieving functioning system builds. It also provides a binary cache, speeding up iteration and deployment.


Take note that this solution reuses the proprietary firmware distributed by The Raspberry Pi Foundation. If that's not desired, one of the ''Other Solutions'' may be preferable.
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.


{{Note|The author of the following section acknowledges that this may not be the best (or even intended) process. These instructions are provided on a best effort basis. If you have a better set of instructions, please contribute them to this section, replacing this content, and removing this notice.}}Setting up a NixOS system on your Raspberry Pi 5 consists of a number of steps. First, it's important to get a SD Image installer onto the device. If you're not currently running on an ARM system (almost definitely the case), you have three options:
== Kernel and hardware defaults ==


# Bootstrap a build machine onto the Raspberry Pi 5, for example with a standard Raspberry Pi OS SD card (use rpi-imager to enable sshd and set wifi credentials for a headless experience), `apt install nix` and run nix as root
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>
# Cross compile the image
# Hope that the compiled image is available in the cache


=== Step 1: Building the SD Image ===
See [[NixOS on ARM/Raspberry Pi#Board profiles|Board profiles]] for Wi-Fi firmware requirements on custom systems.
{{Note|It might be possible to do the following steps via the official SD installer as well. If you manage to do it, please mark this section as optional and remove this notice.}}The project provides build images as well, which are modified versions of the nix-hardware ones. Before getting into building one, in order to make use of the community binary caches, and potentially avoid rebuilding the image, make sure you are added to the trusted users in your own nix configuration:
{{File|||3=trusted-users = username|name=nix.conf|lang=conf}}
Or, alternatively, in your nixos configuration:
{{File|||3={
  nix.settings.trusted-users = [ "your-username" ];
<nowiki>}</nowiki>|name=configuration.nix|lang=nix}}
Afterwards, you can build one of the SD images:<syntaxhighlight lang="console">
$ nix build github:nvmd/nixos-raspberrypi#installerImages.rpi5
</syntaxhighlight>You can either [[Cross Compiling|cross-compile]] the image on your system, or alternatively, you can install the "normal" Raspberry Pi OS on your Raspberry Pi 5, then install Nix standalone (multi-user), and set it up as a [[distributed build]] machine.


Finally, simply copy the image to the current directory from the <code>result</code> directory, extract it and write it to a USB drive, and boot to this drive on the raspberry pi (by default the raspberry pi will first try to boot the SD card, then the USB drive, so just don't put any SD card when booting and plug it later. Note that since the installer will format the SD card, you cannot put the installer on the SD card itself). You can find more information on the [[NixOS on ARM/Installation]] page.
=== Graphics ===


=== Step 2: Installing NixOS ===
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>.


Once you're running an installer image, you can create a flake referencing the repository. For example:{{File|3={
== Storage ==
  description = "Example Raspberry Pi 5 configuration flake";
    inputs = {
      nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
      nixos-raspberrypi.url = "github:nvmd/nixos-raspberrypi/main";
    };


  nixConfig = {
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.
    extra-substituters = [
      "https://nixos-raspberrypi.cachix.org"
    ];
    extra-trusted-public-keys = [
      "nixos-raspberrypi.cachix.org-1:4iMO9LXa8BqhU+Rpg6LQKiGa2lsNh/j2oiYLNOQ5sPI="
    ];
  };


  outputs = { self, nixpkgs, nixos-raspberrypi }@inputs:
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>
    {
      nixosConfigurations = {
        yourHostname = nixos-raspberrypi.lib.nixosSystem {
          specialArgs = inputs;
          modules = [
            ({...}: {
              imports = with nixos-raspberrypi.nixosModules; [
                raspberry-pi-5.base
                raspberry-pi-5.bluetooth
              ];
            })
            ({ ... }: {
              networking.hostName = "yourHostName";
              users.users.yourUserName = {
                initialPassword = "yourInitialPassword";
                isNormalUser = true;
                extraGroups = [
                  "wheel"
                ];
              };


              services.openssh.enable = true;
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.
            })


            ({ ... }: {
== Serial console ==
              fileSystems = {
                "/boot/firmware" = {
                  device = "/dev/disk/by-uuid/2175-794E";
                  fsType = "vfat";
                  options = [
                    "noatime"
                    "noauto"
                    "x-systemd.automount"
                    "x-systemd.idle-timeout=1min"
                  ];
                };
                "/" = {
                  device = "/dev/disk/by-uuid/44444444-4444-4444-8888-888888888888";
                  fsType = "ext4";
                  options = [ "noatime" ];
                };
              };
            })
          ];
        };
      };
    };
<nowiki>}</nowiki>|name=flake.nix|lang=nix}}Finally, simply <code>nixos-rebuild switch --flake .#yourHostname</code> the flake.


== Other Solutions ==
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>
In general, as shown in in the first section, the closed source and proprietary software powering part of the Raspberry Pi development boards is a big source of contention. Therefore, there are largely two kinds of solutions going forward: '''moving towards a generic boot process''', and '''using proprietary software''', each with advantages and disadvantages.


=== Using proprietary software ===
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:
Besides the current ''Proposed Solution'', there has been one more attempt at https://github.com/tstat/raspberry-pi-nix (just follow the example and hints at https://github.com/tstat/raspberry-pi-nix/issues/13) and has the best out-of-the-box experience. You have to remote-build many Nix packages, probably the kernel as well, yourself (e.g. using the [https://wiki.nixos.org/wiki/Distributed_build Pi without NixOS as an intermediate remote builder]) and that can take several hours though.


=== Generic UEFI Boot ===
<syntaxhighlight lang="nix">
This solution is technically more complex than the others, and the overview is separated into sections.
{ lib, ... }:
 
==== Raspberry Pi Boot stages ====
To understand the adaptions for NixOS better, it's helpful to understand more about the stages:
 
1. '''ROM boot loader''': The first-stage boot loader comes "burned in" on the Pi in a tiny
[[wikipedia:Programmable_ROM#One_time_programmable_memory|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].
 
Nothing to adapt here.
 
 
2. '''EEPROM boot loader''': The second-stage boot loader comes built-in on the Pi in a larger, rewriteable
[[wikipedia:EEPROM|EEPROM]].
'''This loader is also very limited and 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, a USB disk, or from the network.
 
This loader (like many second-stage boot loaders of other devices) is so size-constrained that it only contains
the bare minimum 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].
 
See [https://github.com/raspberrypi/rpi-eeprom/releases EEPROM image releases] for improved and wider hardware support.
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
[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>)
of an SD card, NVME SSD or other storage hardware described above.
Because '''size is usually not an issue here, 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 among Linux distros).
 
However, '''the standard Pi 5 setup has no third-stage boot loader'''.
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 files]
in compact binary format <code>*.dtb</code>), some settings (<code>cmdline.txt</code> for kernel settings,
<code>config.txt</code> for firmware settings),
and the Linux kernel itself from a <code>/boot/firmware/</code> folder. On the Pi 5's default Debian image this is
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
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].
 
==== Setting up a generic UEFI NixOS ====
The task to get a generic NixOS setup requires a
 
# UEFI boot loader for Pi 5: There exists a WIP [https://github.com/worproject/rpi5-uefi EDK2 for Pi 5 Github project] but with a few limitations see the project for details.
# systemd-boot boot loader: Works
# generic Linux kernel that works for the Pi 5's ARM v8 processor and hardware: An almost generic Pi 5 compatible kernel exists [https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/5/default.nix at the NixOS-hardware repository]; it's an adaption from a kernel for the Pi 4)
 
  1. ROM -> 2. EEPROM -> 3. UEFI boot loader (EDK2) -> 4. systemd-boot boot loader -> Pi 4/5-adapted NixOS Kernel -> NixOS
1. '''Install EDK2''' (UEFI firmware implementation):
 
We need the first partition of the SD card (or NVMe SSD, etc.) again to be formatted as FAT
but marked as an ESP (EFI System Partition) to conform to (U)EFI standards.
In this partition we need to place the EDK2 firmware 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 EDK2 instead of a Linux loader stub.
 
See the [https://github.com/worproject/rpi5-uefi EDK2 for Pi 5 Github project]; the releases already contain both of these files.
 
See a [https://github.com/NixOS/nixpkgs/issues/260754#issuecomment-1908664693 guide on how to setup partitions and these files].
 
2. '''Install systemd-boot, kernel and NixOS''':
 
The rest is a usual NixOS installation on a second partition with the caveat to '''select a Linux kernel that supports the Pi 5''' like the [https://github.com/NixOS/nixos-hardware/pull/927 Pi 5 compatible Linux kernel is available in nixos-hardware].
 
Follow [https://github.com/NixOS/nixpkgs/issues/260754#issuecomment-1936211154 this guide] to build
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.
 
==== Alternative 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|3=<nowiki>
{
  boot.kernelPackages = (import (builtins.fetchTarball https://gitlab.com/vriska/nix-rpi5/-/archive/main.tar.gz)).legacyPackages.aarch64-linux.linuxPackages_rpi5;
}
</nowiki>|name=configuration.nix|lang=nix}}
 
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 (which is a generic aarch64 kernel for Pi 3 and later models). Although, due to a smaller page size, this will have slightly worse performance:
{{file|||<nowiki>
{
{
   boot.kernelPackages = pkgs.linuxPackages_rpi4;
  hardware.raspberry-pi.configtxt.settings.pi5.enable_uart = lib.mkForce true;
   boot.kernelParams = [ "console=ttyAMA10,115200n8" ];
}
}
</nowiki>|name=configuration.nix|lang=nix}}
</syntaxhighlight>


==== Troubleshooting ====
Test U-Boot interaction after enabling the UART, and use a 3.3 V adapter designed for the Pi 5 debug connector.
 
===== GPU =====
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 without additional configuration (see the nixos-hardware PR linked previously). Note that Xwayland applications may produce broken graphics on KDE; the root cause of this issue has not yet been evaluated.
 
The rpi5-uefi download does not include overlays. You can get them by copying the <code>boot/overlays</code> folder from [https://github.com/raspberrypi/firmware the firmware repository] to <code>/boot</code> (so that <code>/boot/overlays/vc4-kms-v3d-pi5.dtbo</code> is available).
 
===== 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|||<nowiki>
{
  boot.kernelParams = [ "8250.nr_uarts=11" "console=ttyAMA10,9600" "console=tty0"];
}
</nowiki>|name=configuration.nix|lang=nix}}


==== Using the Pi 5 as a remote builder to build native ARM packages for the Pi 5 ====
== Power and cooling ==
Building an NixOS system image that can be flashed to an SD card or NVMe SSD requires to '''build ARM binaries''', more specifically for the <code>"aarch64-linux"</code>platform. From a typical Intel/AMD computer we can either


* '''emulated native compile using QEMU''' virtualization by enabling the [https://docs.kernel.org/admin-guide/binfmt-misc.html binfmt] kernel feature on NixOS configuration setting <code>boot.binfmt.emulatedSystems = [ "aarch64-linux" ];</code>). This can be fast if everything is downloaded pre-compiled from the cache.nixos.org cache and only few packages really need local compilation. In reality it can be extremely slow, e.g. compiling a Linux kernel alone can take days.
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>
* '''cross-compile''' to ARM using as to happen natively, but nothing will be cached from cache.nixos.org as this is not pre-build. So the compile itself is fast but there will be a lot more to compile locally. In practice it's quite fragile, because you may encounter packages that don't really support cross-compilation get stuck.
* '''native compile on an remote builder''' like the Pi 5 itself running its custom Debian Linux at the beginning or later NixOS. This is quite simple to setup and reasonably fast as most packages are pre-build and cached on cache.nixos.org, and building a remaining Linux kernel only takes 2-3h on the Pi 5.
'''Setting up the Pi 5 as a remote native builder''' can be done following the steps at [[Distributed build|https://wiki.nixos.org/wiki/Distributed_build]]. The rough steps are as follows:


# '''Install the Nix package manager''' on Pi 5 Debian OS the normal, multi-user way with <code>sh <(curl -L <nowiki>https://nixos.org/nix/install</nowiki>) --daemon</code>. If you already have NixOS running on the Pi 5, then you can skip this step.
== Alternative implementation ==
# '''Setup a <code>ssh</code> connection''' from your local machine to the Pi, especially adding <code>SetEnv PATH=/nix/var/nix/profiles/default/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin</code> to the Pi's <code>/etc/ssh/sshd_config</code> file. If you already have NixOS running on the Pi 5, then you can skip this step.
# '''Make the remote Pi known to you local computer''' by adding it as a <code>nix.buildMachines</code> entry to your  <code>/etc/nix/configuration.nix</code> file and use connection protocol <code>ssh-ng</code>(!).
# You can then '''build, e.g. an NixOS sd card image''' with a call similar to  <code>nix build .\#nixosConfigurations.pi5.config.system.build.sdImage</code>
# '''flash that resulting image onto an SD card''' or NVMe SSD using a call similar to <code>zstdcat result/sd-image/nixos-sd-image-23.11.20230703.ea4c80b-aarch64-linux.img.zst | sudo dd of=/dev/mmcblk0 bs=100M status=progress</code> and place that card into the Pi 5.


Missing:
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.


# How to do cross-compilation. ( and/or explain why the above emulation is required at all)
== UEFI ==


==== Deploy and Update the Pi 5 NixOS system once it's running NixOS ====
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]].
Once the Pi 5 is running NixOS, you can update it with newer NixOS system configurations using e.g. the usual  <code>nix-rebuild</code> 


tool with a call similar to
== See also ==


<code>nixos-rebuild --flake .#pi5 --build-host piuser@pi5 --target-host piuser@pi5 --use-remote-sudo switch</code>
* [[NixOS on ARM/Raspberry Pi]]
* [[NixOS on ARM/Installation]]
* [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#nvme-ssd-boot Raspberry Pi NVMe documentation]


that uses the SSH connection from the remote builder section.
== References ==


See [https://nixcademy.com/2023/08/10/nixos-rebuild-remote-deployment/ this guide] for a good explanation of this terminal call.
<references />


[[Category:NixOS on ARM]]
[[Category:NixOS on ARM]]

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"