NixOS on ARM/Raspberry Pi 5 - Revision history

Raboof: /* Proposed Solution */ document/promote building on Raspberry Pi OS, an easy way to get going

2026-01-11T12:58:13Z

Proposed Solution: document/promote building on Raspberry Pi OS, an easy way to get going

← Older revision		Revision as of 12:58, 11 January 2026
Line 72:		Line 72:
	{{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:		{{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:

	# ~~Cross compile~~ the ~~image~~ (~~Note: an editor should add how~~-to ~~information~~);		# 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
	# Hope that the compiled image is available in the cache;		# Cross compile the image
	~~# Bootstrap a build machine onto the Raspberry Pi 5.~~		# Hope that the compiled image is available in the cache

	=== Step 1: Building the SD Image ===		=== Step 1: Building the SD Image ===

TobiasBora at 13:44, 17 July 2025

2025-07-17T13:44:49Z

← Older revision		Revision as of 13:44, 17 July 2025
Line 87:		Line 87:
	</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.		</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 the SD card. You can find more information on the [[NixOS on ARM/Installation]] page.		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.

	=== Step 2: Installing NixOS ===		=== Step 2: Installing NixOS ===

DoggoBit: fix syntax highlight lang

2025-06-11T17:20:17Z

fix syntax highlight lang

← Older revision		Revision as of 17:20, 11 June 2025
Line 83:		Line 83:
	nix.settings.trusted-users = [ "your-username" ];		nix.settings.trusted-users = [ "your-username" ];
	<nowiki>}</nowiki>\|name=configuration.nix\|lang=nix}}		<nowiki>}</nowiki>\|name=configuration.nix\|lang=nix}}
	Afterwards, you can build one of the SD images:<syntaxhighlight lang="~~shell~~">		Afterwards, you can build one of the SD images:<syntaxhighlight lang="console">
	$ nix build github:nvmd/nixos-raspberrypi#installerImages.rpi5		$ 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.		</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.

DoggoBit: migrate templates

2025-06-11T17:18:29Z

migrate templates

← Older revision		Revision as of 17:18, 11 June 2025
Line 91:		Line 91:
	=== Step 2: Installing NixOS ===		=== Step 2: Installing NixOS ===

	Once you're running an installer image, you can create a flake referencing the repository. For example:{{File\|~~filename=flake.nix\|language=nix\|contents~~={		Once you're running an installer image, you can create a flake referencing the repository. For example:{{File\|3={
	description = "Example Raspberry Pi 5 configuration flake";		description = "Example Raspberry Pi 5 configuration flake";
	inputs = {		inputs = {
Line 155:		Line 155:
	};		};
	};		};
	<nowiki>}</nowiki>		<nowiki>}</nowiki>\|name=flake.nix\|lang=nix}}Finally, simply <code>nixos-rebuild switch --flake .#yourHostname</code> the flake.
	}}Finally, simply <code>nixos-rebuild switch --flake .#yourHostname</code> the flake.

	== Other Solutions ==		== Other Solutions ==
Line 254:		Line 253:
	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:		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\|~~/etc/nixos/configuration.nix\|nix\|~~<nowiki>		{{file\|3=<nowiki>
	{		{
	boot.kernelPackages = (import (builtins.fetchTarball https://gitlab.com/vriska/nix-rpi5/-/archive/main.tar.gz)).legacyPackages.aarch64-linux.linuxPackages_rpi5;		boot.kernelPackages = (import (builtins.fetchTarball https://gitlab.com/vriska/nix-rpi5/-/archive/main.tar.gz)).legacyPackages.aarch64-linux.linuxPackages_rpi5;
	}		}
	</nowiki>}}		</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>.		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:		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\|~~/etc/nixos/configuration.nix~~\|~~nix~~\|<nowiki>		{{file\|\|\|<nowiki>
	{		{
	boot.kernelPackages = pkgs.linuxPackages_rpi4;		boot.kernelPackages = pkgs.linuxPackages_rpi4;
	}		}
	</nowiki>}}		</nowiki>\|name=configuration.nix\|lang=nix}}

	==== Troubleshooting ====		==== Troubleshooting ====
Line 278:		Line 277:
	===== Bluetooth =====		===== 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\|~~/etc/nixos/configuration.nix~~\|~~nix~~\|<nowiki>		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"];		boot.kernelParams = [ "8250.nr_uarts=11" "console=ttyAMA10,9600" "console=tty0"];
	}		}
	</nowiki>}}		</nowiki>\|name=configuration.nix\|lang=nix}}

	==== Using the Pi 5 as a remote builder to build native ARM packages for the Pi 5 ====		==== Using the Pi 5 as a remote builder to build native ARM packages for the Pi 5 ====

DoggoBit: migrate templates

2025-06-11T17:15:41Z

migrate templates

← Older revision		Revision as of 17:15, 11 June 2025
Line 78:		Line 78:
	=== Step 1: Building the SD Image ===		=== Step 1: Building the SD Image ===
	{{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:		{{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\|~~nix.conf~~\|~~conf~~\|3=trusted-users = username\|name=\|lang=}}		{{File\|\|\|3=trusted-users = username\|name=nix.conf\|lang=conf}}
	Or, alternatively, in your nixos configuration:		Or, alternatively, in your nixos configuration:
	{{File\|~~configuration.nix~~\|~~nix~~\|3={		{{File\|\|\|3={
	nix.settings.trusted-users = [ "your-username" ];		nix.settings.trusted-users = [ "your-username" ];
	<nowiki>}</nowiki>\|name=\|lang=}}		<nowiki>}</nowiki>\|name=configuration.nix\|lang=nix}}
	Afterwards, you can build one of the SD images:<syntaxhighlight lang="shell">		Afterwards, you can build one of the SD images:<syntaxhighlight lang="shell">
	$ nix build github:nvmd/nixos-raspberrypi#installerImages.rpi5		$ nix build github:nvmd/nixos-raspberrypi#installerImages.rpi5

DoggoBit: migrate templates

2025-06-11T17:14:12Z

migrate templates

← Older revision		Revision as of 17:14, 11 June 2025
Line 78:		Line 78:
	=== Step 1: Building the SD Image ===		=== Step 1: Building the SD Image ===
	{{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:		{{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\|~~filename=~~nix.conf\|~~language=~~conf\|~~contents~~=trusted-users = username}}		{{File\|nix.conf\|conf\|3=trusted-users = username\|name=\|lang=}}
	Or, alternatively, in your nixos configuration:		Or, alternatively, in your nixos configuration:
	{{File\|~~filename=~~configuration.nix\|~~language=~~nix\|~~contents~~={		{{File\|configuration.nix\|nix\|3={
	nix.settings.trusted-users = [ "your-username" ];		nix.settings.trusted-users = [ "your-username" ];
	<nowiki>}</nowiki>}}		<nowiki>}</nowiki>\|name=\|lang=}}
	Afterwards, you can build one of the SD images:<syntaxhighlight lang="shell">		Afterwards, you can build one of the SD images:<syntaxhighlight lang="shell">
	$ nix build github:nvmd/nixos-raspberrypi#installerImages.rpi5		$ nix build github:nvmd/nixos-raspberrypi#installerImages.rpi5

DoggoBit: /* Generic UEFI boot support */

2025-06-11T16:22:22Z

Generic UEFI boot support

← Older revision		Revision as of 16:22, 11 June 2025
Line 37:		Line 37:

	=== Generic UEFI boot support ===		=== 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:		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\|
	[[~~File:~~Raspberry Pi 5 ~~Boot Process.png~~\|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.~~\|center\|thumb\|500x500px\|The normal boot process of a Raspberry Pi 5]]~~		ROM --> EEPROM
	~~<!-- I'm including here the Mermaid code to generate this diagram. It would be amazing if we could do -->~~		EEPROM --> FK[Firmware / Kernel]
	~~<!-- this via a template, but until then, here it is: -->~~		FK --> OS[Raspberry Pi OS]
	~~<!-- flowchart LR -->~~		}}\|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.}}
	~~<!-- ROM -\-> EEPROM -->~~
	~~<!-- EEPROM -\-> FK[Firmware / Kernel] -->~~
	~~<!-- FK -\-> OS[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 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:		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:
	[[~~File:~~Raspberry Pi 5 ~~Ideal Boot Process.png~~\|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.~~\|center\|thumb\|500x500px\|The ideal Raspberry Pi 5 boot process]]~~		{{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.''		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:		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:
	[[~~File:~~Raspberry Pi 5 U-Boot ~~Boot Process.png~~\|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.~~\|center\|thumb\|500x500px\|The U-Boot boot process]]~~		{{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.}}


	== Proposed Solution ==		== Proposed Solution ==

Nvmd: update flake url to point to "stable" branch

2025-06-04T13:54:13Z

update flake url to point to "stable" branch

← Older revision		Revision as of 13:54, 4 June 2025
Line 87:		Line 87:
	inputs = {		inputs = {
	nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";		nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
	nixos-raspberrypi.url = "github:nvmd/nixos-raspberrypi";		nixos-raspberrypi.url = "github:nvmd/nixos-raspberrypi/main";
	};		};

Gwennlbh: /* Step 1: Building the SD Image */ fix typo for nvmd/nixos-raspberrypi#installerImages.rpi5

2025-06-04T12:23:26Z

Step 1: Building the SD Image: fix typo for nvmd/nixos-raspberrypi#installerImages.rpi5

← Older revision		Revision as of 12:23, 4 June 2025
Line 76:		Line 76:
	<nowiki>}</nowiki>}}		<nowiki>}</nowiki>}}
	Afterwards, you can build one of the SD images:<syntaxhighlight lang="shell">		Afterwards, you can build one of the SD images:<syntaxhighlight lang="shell">
	$ nix build github:~~nvdm~~/nixos-raspberrypi#installerImages.rpi5		$ 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.		</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.

DoggoBit at 14:35, 3 June 2025

2025-06-03T14:35:51Z

← Older revision		Revision as of 14:35, 3 June 2025
Line 147:		Line 147:
	};		};
	};		};
	}}}Finally, simply <code>nixos-rebuild switch --flake .#yourHostname</code> the flake.		<nowiki>}</nowiki>
			}}Finally, simply <code>nixos-rebuild switch --flake .#yourHostname</code> the flake.

	== Other Solutions ==		== Other Solutions ==