NixOS on ARM/Raspberry Pi: Difference between revisions

imported>Mbrock
Add WiFi firmware configuration for RPi 3B+
Replace outdated Raspberry Pi guidance with current images, nixos-hardware profiles, the U-Boot/extlinux boot flow, firmware management, and declarative config.txt
 
(56 intermediate revisions by 26 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 Family
! colspan="2" class="title" | Raspberry Pi family
|-
|-
|colspan="2"|[[File:raspberry_pi_3_glamour.jpg|frameless|256px|A Raspberry Pi 3 with enclosure.]]
| colspan="2" | [[File:raspberry_pi_3_glamour.jpg|frameless|256px|A Raspberry Pi 3 with enclosure.]]
|-
|-
!colspan="2" class="title"|Raspberry Pi
! Manufacturer
| Raspberry Pi Ltd
|-
|-
!Architecture
! Recommended architecture
|ARMv6
| AArch64 on 64-bit boards
|-
|-
!colspan="2" class="title"|Raspberry Pi 2
! Boot method
| Raspberry Pi firmware and U-Boot
|}
</div>
 
'''Raspberry Pi''' boards use Broadcom systems-on-chip and a board-specific boot process. For 64-bit models, the generic AArch64 SD image is the usual starting point. Raspberry Pi firmware starts U-Boot, which reads the extlinux configuration generated by NixOS. The [https://github.com/NixOS/nixos-hardware/tree/master/raspberry-pi nixos-hardware repository] provides profiles for Raspberry Pi 2, 3, 4, and 5. These profiles select Raspberry Pi downstream kernels and support declarative <code>config.txt</code> generation.<ref name="hardware-readme">[https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/README.md nixos-hardware: Raspberry Pi profiles and modules]</ref>
 
== Support ==
 
AArch64 has an official NixOS binary cache. ARMv6 and ARMv7 can still be built from Nixpkgs, but NixOS does not publish binary caches for them.<ref name="arm-cache">[[NixOS on ARM#Binary caches|NixOS on ARM: binary caches]]</ref>
 
{| class="wikitable"
! Board family
! Recommended architecture
! NixOS image
! <code>nixos-hardware</code> profile
! Notes
|-
| Raspberry Pi 1, Zero, and Zero W
| ARMv6
| Build from Nixpkgs or use a community image
| None
| No official binary cache
|-
| Raspberry Pi 2
| ARMv7
| Build from Nixpkgs or use a community image
| <code>raspberry-pi-2</code>
| No official binary cache. The profile targets 32-bit ARMv7 and enables OpenSSH by default. Later BCM2837-based revisions can run AArch64, but there is no dedicated 64-bit profile.
|-
| Raspberry Pi Zero 2 W
| AArch64
| Generic AArch64 SD image
| None
| The image contains Zero 2 W boot files, but there is no dedicated board profile.
|-
|-
!Architecture
| [[NixOS on ARM/Raspberry Pi 3|Raspberry Pi 3]]
|ARMv7
| AArch64
| Generic AArch64 SD image
| <code>raspberry-pi-3</code>
| ARMv7 is a best-effort alternative.
|-
|-
!colspan="2" class="title"|Raspberry Pi 3
| [[NixOS on ARM/Raspberry Pi 4|Raspberry Pi 4, Pi 400, and CM4]]
| AArch64
| Generic AArch64 SD image
| <code>raspberry-pi-4</code>
| The profile includes optional modules for several peripherals and HATs.
|-
|-
!Architecture
| [[NixOS on ARM/Raspberry Pi 5|Raspberry Pi 5, Raspberry Pi 500, Raspberry Pi 500+, and Compute Module 5]]
|AArch64 + ARMv7
| AArch64
| Generic AArch64 SD image on unstable
| <code>raspberry-pi-5</code>
| NixOS 26.05 images do not include the Pi 5 boot files. 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>
|}
|}
</div>
<!-- TODO : write intro paragraph -->
== Status ==


Only the ''Raspberry Pi 3'' is supported upstream, with the aarch64 effort.
Peripheral support depends on the selected kernel, device tree, firmware, and board revision.
 
== Installation ==
 
=== Generic AArch64 image ===
 
For the Zero 2 W, Pi 3, and Pi 4 families, download a current AArch64 SD image from the [[NixOS on ARM/Installation#SD card images (SBCs and similar platforms)|ARM installation page]]. For Pi 5, use a <code>nixos-unstable</code> image containing PR #537862. NixOS 26.05 images do not contain the required boot files.<ref name="pi5-image" /> The standard installation path uses an ARM SD image rather than the PC-oriented NixOS ISO. UEFI is a separate advanced setup.


Other Raspberry Pis are part of '''@dezgeg''''s porting efforts to ARMv6 and ARMv7.
Write the decompressed image to a microSD card as described on the ARM installation page. Check the destination device carefully because writing the image erases it. The SD image contains a mutable NixOS system, so after the first boot you can create a configuration and use <code>nixos-rebuild</code> without running a separate installer.


== Board-specific installation notes ==
The stock image uses the generic NixOS kernel. Import a board profile if you need the Raspberry Pi downstream kernel or the board-specific options described below.


First follow the [[NixOS_on_ARM#Installation|generic installation steps]] to get the installer image and install using the [[NixOS_on_ARM#NixOS_installation_.26_configuration|installation and configuration steps]].
=== Custom SD image ===


=== Raspberry Pi (1) ===
A custom image can combine the Nixpkgs AArch64 image module with a <code>nixos-hardware</code> profile. When a custom image imports both modules, the profile's firmware module replaces the stock firmware population hook. Enable U-Boot explicitly so that the image contains <code>u-boot.bin</code> and the corresponding <code>kernel=</code> entry in <code>config.txt</code>.


The ARMv6 image boots out-of-the-box.
<syntaxhighlight lang="nix">
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nixos-hardware = {
      url = "github:NixOS/nixos-hardware/master";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };


=== Raspberry Pi 2 ===
  outputs = { nixpkgs, nixos-hardware, ... }: {
    nixosConfigurations.rpi4-image = nixpkgs.lib.nixosSystem {
      system = "aarch64-linux";
      modules = [
        "${nixpkgs}/nixos/modules/installer/sd-card/sd-image-aarch64.nix"
        nixos-hardware.nixosModules.raspberry-pi-4
        ({ lib, ... }: {
          # The pinned Raspberry Pi kernel does not build the ZFS module.
          boot.supportedFilesystems.zfs = lib.mkForce false;
          hardware.raspberry-pi.firmware.uboot.enable = true;
        })
        ./configuration.nix
      ];
    };
  };
}
</syntaxhighlight>


The ARMv7 image should boot out-of-the-box, though the author hasn't personally tested this.
Build <code>nixosConfigurations.rpi4-image.config.system.build.sdImage</code>. The ZFS override stops the base NixOS image profile from building an incompatible out-of-tree module. This ext4 image does not use ZFS. A system that requires ZFS must select a kernel supported by the packaged ZFS module.


=== Raspberry Pi 3 ===
A board profile does not define a disk layout. Its firmware population step supports cross-compilation, but support in other packages varies.<ref name="cross-image">[https://github.com/NixOS/nixos-hardware/pull/1945 nixos-hardware PR #1945: fix cross-compiled SD images]</ref>


Both the AArch64 and ARMv7 images boot out-of-the-box. Using the 64-bit AArch64 image is highly recommended, as the availability of binaries is much better and allows the use of the 64-bit instruction set.
== Board profiles ==


Use the following GPIO Pins with an USB-TTL connector:
The flake module names are:
<syntaxhighlight>
 
GND        - 3rd in top row, black cable
{| class="wikitable"
GPIO 14 TXD - 4th in top row, white cable
! Board
GPIO 15 RXD - 5th in top row, green cable
! Flake module
</syntaxhighlight>
! Channel import
Use <code>nix-shell -p screen --run "screen /dev/ttyUSB0 115200"</code> to connect to the console.
|-
{{note|Right now (2017-10-08) wifi is not working out of the box on the Raspberrypi 3, you will need to use ethernet. Add the following to your configuration.nix. This requires linux kernel > 4.13.0 }}
| Raspberry Pi 2
<syntaxhighlight lang=nix>
| <code>nixos-hardware.nixosModules.raspberry-pi-2</code>
| <code>&lt;nixos-hardware/raspberry-pi/2&gt;</code>
|-
| Raspberry Pi 3
| <code>nixos-hardware.nixosModules.raspberry-pi-3</code>
| <code>&lt;nixos-hardware/raspberry-pi/3&gt;</code>
|-
| Raspberry Pi 4
| <code>nixos-hardware.nixosModules.raspberry-pi-4</code>
| <code>&lt;nixos-hardware/raspberry-pi/4&gt;</code>
|-
| Raspberry Pi 5
| <code>nixos-hardware.nixosModules.raspberry-pi-5</code>
| <code>&lt;nixos-hardware/raspberry-pi/5&gt;</code>
|}
 
A flake configuration for a Pi 4 can import the profile as follows:
 
<syntaxhighlight lang="nix">
{
{
   ...
   inputs = {
  hardware.enableRedistributableFirmware = true;
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  hardware.firmware = [
    nixos-hardware = {
     (pkgs.stdenv.mkDerivation {
      url = "github:NixOS/nixos-hardware/master";
    name = "broadcom-rpi3-extra";
      inputs.nixpkgs.follows = "nixpkgs";
    src = pkgs.fetchurl {
    };
    url = "https://raw.githubusercontent.com/RPi-Distro/firmware-nonfree/54bab3d/brcm80211/brcm/brcmfmac43430-sdio.txt";
  };
    sha256 = "19bmdd7w0xzybfassn7x4rb30l70vynnw3c80nlapna2k57xwbw7";
 
    };
  outputs = { nixpkgs, nixos-hardware, ... }: {
    phases = [ "installPhase" ];
    nixosConfigurations.rpi4 = nixpkgs.lib.nixosSystem {
    installPhase = ''
      system = "aarch64-linux";
    mkdir -p $out/lib/firmware/brcm
      modules = [
    cp $src $out/lib/firmware/brcm/brcmfmac43430-sdio.txt
        nixos-hardware.nixosModules.raspberry-pi-4
    '';
        ./configuration.nix
    })
      ];
  ];
    };
   networking.wireless.enable = true;
   };
}
}
</syntaxhighlight>
</syntaxhighlight>


=== Raspberry Pi 3B+ ===
With channels, add <code>nixos-hardware</code> and import the matching path:


Here is a similar incantation as above, but for the Raspberry Pi 3B+:
<syntaxhighlight lang="nix">
 
<syntaxhighlight lang=nix>
{
{
   ...
   imports = [
  hardware.enableRedistributableFirmware = true;
     <nixos-hardware/raspberry-pi/4>
  hardware.firmware = [
     (pkgs.stdenv.mkDerivation {
    name = "broadcom-rpi3bplus-extra";
    src = pkgs.fetchurl {
    url = "https://raw.githubusercontent.com/RPi-Distro/firmware-nonfree/b518de4/brcm/brcmfmac43455-sdio.txt";
    sha256 = "0r4bvwkm3fx60bbpwd83zbjganjnffiq1jkaj0h20bwdj9ysawg9";
    };
    phases = [ "installPhase" ];
    installPhase = ''
    mkdir -p $out/lib/firmware/brcm
    cp $src $out/lib/firmware/brcm/brcmfmac43455-sdio.txt
    '';
    })
   ];
   ];
  networking.wireless.enable = true;
}
}
</syntaxhighlight>
</syntaxhighlight>


<s>Until the kernel 3.18 is finalized, this will require a temporary work-around image. See also the note in the [[#Serial console]] section.</s> The workaround is no longer needed:
Pin the <code>nixos-hardware</code> revision with the rest of the system inputs rather than following its moving <code>master</code> branch indefinitely.
 
The stock image enables redistributable firmware. The Pi 4 profile also installs a pinned Wi-Fi and Bluetooth firmware package. The Pi 3 and Pi 5 profiles do not add wireless firmware themselves, so a custom system based only on either profile may need <code>hardware.enableRedistributableFirmware</code> or an explicit firmware package.
 
== Boot process ==
 
The official AArch64 image uses this path:
 
<code>ROM or EEPROM &rarr; Raspberry Pi firmware &rarr; U-Boot &rarr; extlinux.conf &rarr; NixOS generation</code>
 
The Raspberry Pi firmware reads the FAT firmware partition and starts U-Boot. <code>boot.loader.generic-extlinux-compatible</code> generates the <code>extlinux.conf</code> file that U-Boot reads. Its entries provide the NixOS generation menu and rollback support.
 
Board profiles enable extlinux generation and import the Raspberry Pi firmware module. They do not define a disk layout. When an <code>sdImage</code> module is also imported, the firmware module populates the image's firmware partition automatically. Include U-Boot by setting <code>hardware.raspberry-pi.firmware.uboot.enable</code>. On a running system, firmware-partition updates require <code>hardware.raspberry-pi.firmware.enable</code>.
 
The <code>nixos-hardware</code> repository does not provide a <code>boot.loader.raspberry-pi</code> module for direct firmware-to-kernel boot. Its firmware module supplies files for the existing U-Boot and extlinux path.<ref name="firmware-source">[https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/common/firmware.nix nixos-hardware firmware module source]</ref>


* https://github.com/NixOS/nixpkgs/issues/22014#issuecomment-399715748
== Firmware partition ==


== Serial console==
The <code>hardware.raspberry-pi.firmware</code> module installs Raspberry Pi boot firmware, device trees, overlays, a rendered <code>config.txt</code>, and optionally U-Boot. Custom images use it at build time. On a running system, it acts only when <code>hardware.raspberry-pi.firmware.enable</code> is true. The option is disabled by default.


Your configuration.nix will need to add <code>console=ttyS0,115200n8</code> to the <code>boot.kernelParams</code> configuration to use the serial console.
The stock generic image instead uses the static Nixpkgs firmware population hook. Later <code>nixos-rebuild</code> operations do not refresh its FAT partition. Enable the firmware module when the partition contents must follow the system configuration.


{{note|For the Raspberry Pi 3B+ it has been reported that the console may be <tt>ttyS1</tt> instead of <tt>ttyS0</tt>.}}
To manage the partition during <code>nixos-rebuild switch</code>, mount its FAT filesystem at <code>/boot/firmware</code> and enable both firmware installation and U-Boot:


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
<syntaxhighlight lang="nix">
{ config, pkgs, lib, ... }:
{
{
   boot.kernelParams = [
   hardware.raspberry-pi.firmware = {
     "console=ttyS0,115200n8"
     enable = true;
   ];
    uboot.enable = true;
   };
}
}
</nowiki>}}
</syntaxhighlight>
 
Set <code>hardware.raspberry-pi.firmware.path</code> if the partition is mounted elsewhere. The activation script checks that the path is a mount point and skips the update with a warning if it is not mounted.


== Camera ==
{{warning|The firmware module owns the files it copies. On every switch it replaces <code>config.txt</code>, copied device trees, copied overlays, and selected GPU firmware files. It removes stale <code>*.dtb</code> files from the partition root and unrecognised entries under <code>overlays/</code>. Do not keep manual changes or unrelated overlay files in those locations.}}


For the camera to work, you will need to add the following code to your configuration.nix:  
The default U-Boot package is <code>pkgs.ubootRaspberryPiAarch64</code>, which covers the 64-bit profiles. A 32-bit Pi 2 configuration must select its matching package:


{{note| Two pull requests ({{pull|38490}} and {{pull|38342}}) are required to make this configuration.nix and the camera working.}}
<syntaxhighlight lang="nix">
{{file|/etc/nixos/configuration.nix|nix|<nowiki>
{ pkgs, ... }:
{ config, pkgs, lib, ... }:
{
{
   boot.loader.raspberryPi.enable = true;
   hardware.raspberry-pi.firmware.uboot = {
  # Set the version depending on your raspberry pi.  
    enable = true;
  boot.loader.raspberryPi.version = 3;
     package = pkgs.ubootRaspberryPi2;
  # We need uboot
   };
  boot.loader.raspberryPi.uboot.enable = true;
  # These two parameters are the important ones to get the
  # camera working. These will be appended to /boot/configuration.txt.
  boot.loader.raspberryPi.firmwareConfig = ''
     start_x=1
    gpu_mem=256
   '';
}
}
</nowiki>}}
</syntaxhighlight>
{{note| A reboot is required to load the new firmware configuration.}}
 
This module updates files on the firmware partition. It does not create partitions and does not update the Pi 4 or Pi 5 bootloader EEPROM.
 
== Declarative config.txt ==


To make the camera available as v4l device under <code>/dev/video0</code> the <code>bcm2835-v4l2</code> kernel module need to be loaded. This can be done by adding the following code to your configuration.nix:
Board profiles generate <code>config.txt</code> from <code>hardware.raspberry-pi.configtxt.settings</code>.<ref name="config-source">[https://github.com/NixOS/nixos-hardware/blob/master/raspberry-pi/common/config-txt.nix nixos-hardware config.txt module source]</ref> Top-level attributes are Raspberry Pi conditional filters such as <code>all</code>, <code>pi4</code>, <code>pi5</code>, and <code>cm4</code>. Lists render the same key more than once.


{{file|/etc/nixos/configuration.nix|nix|<nowiki>
<syntaxhighlight lang="nix">
{ config, pkgs, lib, ... }:
{ lib, ... }:
{
{
   boot.kernelModules = [ "bcm2835-v4l2" ];
   hardware.raspberry-pi.configtxt.settings = {
    all = {
      dtparam = [
        "audio=on"
        "i2c_arm=on"
      ];
      dtoverlay = [
        "vc4-kms-v3d"
        "disable-bt"
      ];
      arm_boost = lib.mkForce null;
    };
    pi5.arm_freq = 2400;
  };
}
}
</nowiki>}}
</syntaxhighlight>
 
Booleans render as <code>1</code> or <code>0</code>. Use <code>lib.mkForce null</code> to remove a default. An ordinary assignment supersedes the profile's lower-priority <code>mkDefault</code> list, while equal-priority list definitions may concatenate. Retain any default entries that are still required. To provide a complete custom file instead, set <code>hardware.raspberry-pi.configtxt.file</code> to a path.
 
Changes reach a running board only when an image builder or the enabled firmware module writes the generated file to the mounted firmware partition.
 
== Kernels and device trees ==
 
The generic AArch64 image uses the generic NixOS kernel. The <code>nixos-hardware</code> profiles instead select a pinned kernel from Raspberry Pi's downstream Linux tree. The downstream kernel may support Raspberry Pi-specific hardware that the mainline kernel does not. The mainline kernel follows the normal NixOS update and maintenance path. Choose the kernel that supports the required hardware and test it on the target board.


== Binary Cache ==
Two mechanisms apply device-tree overlays:


Depending on the architecture used, binary caches availability varies. Binary caches instructions are on the main [[NixOS on ARM#Binary cache|NixOS on ARM]] page. The following table desribes the architectures supported by each board.  
* <code>hardware.raspberry-pi.configtxt.settings</code> asks the Raspberry Pi firmware to apply overlays at boot.
* <code>hardware.deviceTree.overlays</code> merges overlays into kernel device trees while building the system.


{|class="wikitable"
The mechanisms can conflict. Loading a generation device tree can discard firmware overlays and runtime fixups, whereas retaining the firmware-provided tree can omit build-time overlays. [https://github.com/NixOS/nixos-hardware/issues/1946 nixos-hardware issue #1946] tracks work on a single firmware-managed mechanism. Test configurations that use both mechanisms and verify the final device tree seen by Linux.
|-
 
! Raspberry Pi 1
== Operational notes ==
| armv6
 
|-
=== EEPROM updates ===
! Raspberry Pi 2
 
| armv7
Pi 4 and Pi 5 use a rewritable bootloader EEPROM. Its version and boot order affect USB, network, and NVMe boot behaviour. Use the <code>raspberrypi-eeprom</code> package and follow the [https://www.raspberrypi.com/documentation/computers/configuration.html#update-bootloader-version official Raspberry Pi bootloader update instructions]. Point <code>BOOTFS</code> at the mounted firmware partition when the tool cannot find it automatically.
|-
 
!rowspan="2" style="vertical-align: middle;"|Raspberry Pi 3
Updating the EEPROM alone does not provide the complete NixOS boot chain. Released U-Boot 2026.07 cannot read a Pi 5 NVMe device during the extlinux stage. The Pi 5 page describes this limitation.
| armv7
 
|-
=== Wi-Fi power saving ===
| aarch64
 
|}
If a board becomes slow or unreachable over Wi-Fi, disable NetworkManager power saving and test again:
 
<syntaxhighlight lang="nix">
{
  networking.networkmanager.wifi.powersave = false;
}
</syntaxhighlight>
 
=== Power supply ===


== Notes about the boot process ==
Undervoltage can cause storage errors, USB resets, display failures, or unexpected reboots. Use a supply and cable rated for the board and attached peripherals. See the [https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply Raspberry Pi power-supply documentation].


=== Raspberry Pi (all versions) ===
=== No output after U-Boot ===


USB keyboards and HDMI displays work perfectly.
<code>Starting kernel ...</code> is normally the last message printed by U-Boot. If the system continues to boot without visible kernel messages, check the kernel <code>console=</code> parameters. Add <code>console=tty0</code> for display output or configure the serial console used by the board.


Using the 3.3v serial port via the pin headers (exact location depends on hardware version) will get u-boot output and, when configured, a Linux kernel console.
== Alternative implementations ==


== Troubleshooting ==
The [https://github.com/nvmd/nixos-raspberrypi nvmd/nixos-raspberrypi] project is a separate community implementation for Zero 2 W and Raspberry Pi 3, 4, and 5. It publishes images and a binary cache. Its direct firmware-to-kernel boot path uses matched kernel and firmware bundles. Pi 5-specific modules include separate VC4 and RP1 display paths. Its module API and bootloader are not part of Nixpkgs or <code>nixos-hardware</code>.


=== Power issues ===
The [https://github.com/nix-community/raspberry-pi-nix nix-community/raspberry-pi-nix] community implementation was archived in March 2025 and is now read-only. For third-party UEFI firmware on Pi 5, see the [[NixOS on ARM/Raspberry Pi 5#UEFI|Pi 5 UEFI notes]].


Especially with the power-hungry Raspberry Pi 3, it is important to have a [https://www.raspberrypi.org/documentation/hardware/raspberrypi/power/README.md sufficient enough power supply] or ''weirdness'' may happen. Weirdness may include:
== See also ==


* Lightning bolt on HDMI output "breaking" the display.
* [[NixOS on ARM/Installation]]
* Screen switching back to u-boot text
* [[NixOS on ARM/Building Images]]
** Fixable temporarily when power is sufficient by swtiching VT (alt+F2 / alt+F1)
* [[U-Boot#Using NixOS with U-Boot|Using NixOS with U-Boot]]
* Random hangs
* [https://www.raspberrypi.com/documentation/computers/config_txt.html Raspberry Pi <code>config.txt</code> documentation]


This problem is a hard problem. It is caused by the Raspberry Pi warning about power issues, but the current drivers (as of
== References ==
Linux 4.14) have a hard time dealing with it properly. If the power supply is rated properly AND the cable is not incurring too much power losses, it may be required to disable the lightning bolt indicator so the display driver isn't messed up.<ref>https://logs.nix.samueldr.com/nixos/2017-12-20#1513784657-1513784714;</ref> The lightning bolt indicator can be disabled by adding the line <code>avoid_warnings=1</code> in config.txt<ref>https://www.raspberrypi.org/documentation/configuration/config-txt/README.md</ref>


{{note|A ''properly rated'' USB power supply, AND a good cable are necessary. The cable has to be short enough to not incur power losses through the length. Do note that thin and cheap cables usually have thinner copper wires, which in turn accentuates power losses.}}
<references />


<hr />
[[Category:NixOS on ARM]]