NixOS on ARM/Raspberry Pi 4
The Raspberry Pi 4 family works with the generic AArch64 SD image and has a board profile in nixos-hardware. The profile selects a Raspberry Pi downstream kernel and includes the Pi 4 initrd modules and Wi-Fi and Bluetooth firmware. It requests full KMS and provides optional modules for Pi 4 peripherals and HATs.
| Raspberry Pi 4 family | |
|---|---|
| |
| Manufacturer | Raspberry Pi Ltd |
| Architecture | AArch64 |
| Boot method | Raspberry Pi EEPROM and firmware, U-Boot, and extlinux |
| SoC | BCM2711 |
| Variants | Pi 4B, Pi 400, CM4, and CM4S |
Installation
Use the generic AArch64 SD image described on the family page. It contains boot files for Pi 4B, Pi 400, CM4, and CM4S.[1] In a flake, import nixos-hardware.nixosModules.raspberry-pi-4. With channels, import <nixos-hardware/raspberry-pi/4>. The family page provides complete examples and explains that a profile is not a bootable image.
Profile defaults
The Pi 4 profile selects a pinned kernel from Raspberry Pi's downstream Linux tree and limits generation device trees to bcm2711-rpi-*.dtb. Its initrd includes the BCM2711 PCIe and VL805 reset drivers. The profile also installs pinned Wi-Fi and Bluetooth firmware, disables GRUB, and enables extlinux generation.[2]
The shared config.txt defaults request full VC4 KMS with dtoverlay=vc4-kms-v3d.[3] The compatibility option hardware.raspberry-pi."4".fkms-3d.enable is disabled by default and is not the normal graphics path.
Optional hardware modules
The Pi 4 profile imports the following options, all disabled by default. Each path starts with hardware.raspberry-pi."4"..
| Hardware | Option suffixes | Purpose |
|---|---|---|
| Audio and Bluetooth | audio.enable, bluetooth.enable
|
Adds a build-time audio node or Bluetooth UART pin routing. Enable the corresponding NixOS audio or Bluetooth services separately. |
| USB controllers | dwc2.enable, dwc2.dr_mode, xhci.enable
|
Configures the DWC2 dual-role controller or the BCM2711 XHCI node. |
| GPIO, I2C, and PWM | gpio.enable, i2c0.enable, i2c1.enable, pwm0.enable
|
Adds GPIO permissions, enables an I2C controller, or enables PWM0 on GPIO 18. Both I2C options also accept frequency.
|
| Official display | backlight.enable, touch-ft5406.enable
|
Adds support nodes for the original official touch display and its FT5406 controller. |
| HATs and capture devices | digi-amp-plus.enable, poe-hat.enable, poe-plus-hat.enable, tv-hat.enable, tc358743.enable
|
Configures the listed audio, PoE fan, TV tuner, or HDMI-to-CSI hardware. The PoE options expose fan temperature and hysteresis settings. |
| LEDs | leds.eth.disable, leds.act.disable, leds.pwr.disable
|
Disables the selected Ethernet, activity, or power LED behaviour on supported Pi 4 boards. |
The exact option definitions are in the Pi 4 profile directory. Some options apply only to the Pi 4B and exclude Compute Module variants.
Device-tree overlay limitation
These optional modules use hardware.deviceTree.overlays, while hardware.raspberry-pi.configtxt.settings uses a separate firmware-time mechanism. The mechanisms can conflict. See Kernels and device trees. nixos-hardware issue #1946 tracks the migration.
The base profile leaves hardware.raspberry-pi."4".apply-overlays-dtmerge.enable disabled. Some peripheral modules enable it when they require the Raspberry Pi dtmerge implementation. Do not enable it as a general installation step.
EEPROM and USB boot
The Pi 4 bootloader lives in a rewritable EEPROM. USB or network boot may require a suitable EEPROM release and BOOT_ORDER. The hardware.raspberry-pi.firmware module manages files on the FAT firmware partition but does not update this EEPROM. Use the raspberrypi-eeprom package and the official update procedure.
The Pi 4B has two micro-HDMI outputs. Linux names the connector marked HDMI0 as HDMI-A-1 and HDMI1 as HDMI-A-2.[4] If a text console or display manager appears on an unexpected output, check both connectors and use a kernel video= parameter when a fixed mapping is required.
For intermittent Wi-Fi reachability problems, see the power-saving note on the family page.