NixOS on ARM/Raspberry Pi 4

From NixOS Wiki
Jump to: navigation, search
Raspberry Pi 4 Family
(Image not available)
Manufacturer Raspberry Pi Foundation
Architecture AArch64
Bootloader Custom or U-Boot
Boot order Configurable; SD, USB, Netboot
Raspberry Pi 4B
SoC BCM2711

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).


The Raspberry Pi 4 Family is only supported as AArch64. Use as armv7 is community supported.

Board-specific installation notes

First follow the generic installation steps to get the installer image and install using the installation and configuration steps.

The Raspberry Pi 4B should work with either the generic SD image or the new kernel variant, starting with 21.05 (or unstable). As long as a kernel 5.10 or newer is in use.

Please note: to uncompress the .zstd, one may use the unzstd command (equivalent to zstd -d) on supported machines. The zstd commands can be accessed from the zstd package.


Using nixos-generate-config will not generate the required minimal configuration.

Remember to add the nixos-unstable channel.

{ config, pkgs, lib, ... }:

 # This configuration worked on 09-03-2021 nixos-unstable @ commit 102eb68ceec
 # The image used

  boot = {
    kernelPackages = pkgs.linuxPackages_rpi4;
    tmpOnTmpfs = true;
    initrd.availableKernelModules = [ "usbhid" "usb_storage" ];
    # ttyAMA0 is the serial console broken out to the GPIO
    kernelParams = [
        # Some gui programs need this

  boot.loader.raspberryPi = {
    enable = true;
    version = 4;
  boot.loader.grub.enable = false;
  boot.loader.generic-extlinux-compatible.enable = true;

  # Required for the Wireless firmware
  hardware.enableRedistributableFirmware = true;

  networking = {
    hostName = "nixos-raspi-4"; # Define your hostname.
    networkmanager = {
      enable = true;

  environment.systemPackages = with pkgs; [

  users = {
    defaultUserShell = pkgs.zsh;
    mutableUsers = false;
    users.root = {
      password = "apassword";
    users.anormaluser = {
      isNormalUser = true;
      password = "apassword";
      extraGroups = [ "wheel" ]; # Enable ‘sudo’ for the user.

  environment.variables = {
    EDITOR = "nvim";

  programs.zsh = {
    enable = true;
    syntaxHighlighting.enable = true;
    interactiveShellInit = ''
      source ${pkgs.grml-zsh-config}/etc/zsh/zshrc
    promptInit = ""; # otherwise it'll override the grml prompt

  nix = {
    autoOptimiseStore = true;
    gc = {
      automatic = true;
      dates = "weekly";
      options = "--delete-older-than 30d";
    # Free up to 1GiB whenever there is less than 100MiB left.
    extraOptions = ''
      min-free = ${toString (100 * 1024 * 1024)}
      max-free = ${toString (1024 * 1024 * 1024)}

  # Assuming this is installed on top of the disk image.
  fileSystems = {
    "/" = {
      device = "/dev/disk/by-label/NIXOS_SD";
      fsType = "ext4";
      options = [ "noatime" ];

  nixpkgs.config = {
    allowUnfree = true;
  powerManagement.cpuFreqGovernor = "ondemand";
  system.stateVersion = "20.09";
  #swapDevices = [ { device = "/swapfile"; size = 3072; } ];

USB boot

For USB booting to work properly, firmware update might be needed:

nix-shell -p raspberrypi-eeprom
rpi-eeprom-update -d -a

Now reboot the device so it can update the firmware from boot partition.

When running from USB device without SD card present, kernel spams log about missing SD card, workaround for this is to set:

boot.loader.raspberryPi.firmwareConfig = "dtparam=sd_poll_once=on";

GPU support

The following configuration samples are built on the assumption that they are added to an already working configuration. They are not complete configurations.

Without GPU

  services.xserver = {
    enable = true;
    displayManager.lightdm.enable = true;
    desktopManager.gnome3.enable = true;
    videoDrivers = [ "fbdev" ];

With GPU

Warning: The device tree overlays provided with the RaspberryPi Kernel don't seem to be compatible with dtc. We might need to add support for the `dtmerge` tool as an alternative, or ask upstream to fix their overlays (or dtc).

See for details.

{ pkgs, ... }:

  hardware.opengl = {
    enable = true;
    setLdLibraryPath = true;
    package = pkgs.mesa_drivers;
  hardware.deviceTree = {
    kernelPackage = pkgs.linux_rpi4;
    overlays = [ "${pkgs.device-tree_rpi.overlays}/vc4-fkms-v3d.dtbo" ];
  services.xserver = {
    enable = true;
    displayManager.lightdm.enable = true;
    desktopManager.gnome3.enable = true;
    videoDrivers = [ "modesetting" ];
  boot.loader.raspberryPi.firmwareConfig = ''


The raspberry tools are available in the libraspberrypi package and include commands like vcgencmd to measure temperature and CPU frequency.


In addition to the usual config, you will need to enable audio support explicitly in the firmwareConfig.

  sound.enable = true;
  hardware.pulseaudio.enable = true;

  boot.loader.raspberryPi.firmwareConfig = ''


Power issues

The Raspberry Pi 4B is as power-hungry, if not more, as its predecessors. It is important to have a sufficient enough power supply or weirdness may happen. Weirdness may include:

  • Lightning bolt icon on HDMI output "breaking" the display.
  • Screen switching back to u-boot text
    • Fixable temporarily when power is sufficient by switching VT (alt+F2 / alt+F1)
  • Random hangs
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.

Note that the Type-C USB receptacle for the Raspberry Pi 4B does not implement Power Delivery (USB PD). This means that it is limited to whatever the power supply will provide when not negotiating power, which is most likely 5V at some undetermined power level.

First Install Issues

Make sure that you resize the NIXOS_SD partition and expand the filesystem so that the initial install will have enough space for the /nix/store. Assuming you only have the SD card plugged in:

$ sudo parted resizepart 2 100%
$ sudo resize2fs /dev/disk/by-label/NIXOS_SD

You might also have to add the nix channels manually.

$ sudo mkdir -p /nix/var/nix/profiles/per-user/root/channels/
$ nix-channel --add nixpkgs
$ nix-channel --update

Finally, the nixos-install program might fail to copy your configuration.nix and hardware-configuration.nix files automatically to /etc/nixos/. You can do this yourself by sudo cp /mnt/etc/nixos/* /etc/nixos/.