NixOS on ARM/UEFI - Revision history

Axx: Clarify / renumber header level, add warning that the "NixOS unstable, new kernel, no ZFS" hasn't built in over a year.

2026-08-28T09:19:48Z

Clarify / renumber header level, add warning that the "NixOS unstable, new kernel, no ZFS" hasn't built in over a year.

← Older revision		Revision as of 09:19, 28 August 2026
Line 10:		Line 10:
	This section of the NixOS on ARM documentation aims to document as much as possible about booting ''any'' ARM boards using UEFI. This will be written with a heavy bias about ''Single Board Computers'' (SBCs), as this is where booting is seen as complicated, cumbersome, when not described as impossible.		This section of the NixOS on ARM documentation aims to document as much as possible about booting ''any'' ARM boards using UEFI. This will be written with a heavy bias about ''Single Board Computers'' (SBCs), as this is where booting is seen as complicated, cumbersome, when not described as impossible.

	== The Basics First == <!--T:4-->		= The Basics First = <!--T:4-->

	=== Target Support === <!--T:5-->		== Target Support == <!--T:5-->

	<!--T:6-->		<!--T:6-->
Line 20:		Line 20:
	Just as you could on <tt>x86_64</tt> if your platform required it, you can build a customized iso image. Explaining this is out of scope for this article. The same pitfalls apply. For example, the generated configuration will not take into account configuring the customized kernel.		Just as you could on <tt>x86_64</tt> if your platform required it, you can build a customized iso image. Explaining this is out of scope for this article. The same pitfalls apply. For example, the generated configuration will not take into account configuring the customized kernel.

	=== Platform Firmware === <!--T:8-->		== Platform Firmware == <!--T:8-->

	<!--T:9-->		<!--T:9-->
Line 28:		Line 28:
	In the ARM with SBCs landscape, '''''[[U-Boot]]''''' is the de facto solution for the ''Platform Firmware''. Though ''U-Boot'' is confusingly, but rightly, often referred to as a ''Boot Loader''. ''U-Boot'' plays double duties often. It is tasked with ''initializing the hardware'', and often also used to handle ''loading and booting'' the operating system.		In the ARM with SBCs landscape, '''''[[U-Boot]]''''' is the de facto solution for the ''Platform Firmware''. Though ''U-Boot'' is confusingly, but rightly, often referred to as a ''Boot Loader''. ''U-Boot'' plays double duties often. It is tasked with ''initializing the hardware'', and often also used to handle ''loading and booting'' the operating system.

	=== UEFI === <!--T:11-->		== UEFI == <!--T:11-->

	<!--T:12-->		<!--T:12-->
Line 36:		Line 36:
	There are multiple implementations of UEFI. Vendors like ''American Megatrends'', ''Phoenix Technologies'' and ''Insyde Software'' may have produced the one on your personal <tt>x86_64</tt> machine. '''TianoCore''' is ''the'' reference UEFI implementation, and Open Source. Luckily enough, ''U-Boot'' implements enough (and a bit more) of the UEFI spec.		There are multiple implementations of UEFI. Vendors like ''American Megatrends'', ''Phoenix Technologies'' and ''Insyde Software'' may have produced the one on your personal <tt>x86_64</tt> machine. '''TianoCore''' is ''the'' reference UEFI implementation, and Open Source. Luckily enough, ''U-Boot'' implements enough (and a bit more) of the UEFI spec.

	==== SBBR? EBBR? ==== <!--T:14-->		=== SBBR? EBBR? === <!--T:14-->

	<!--T:15-->		<!--T:15-->
	Other than letter salads, they are ''Server Base Boot Requirements'' and ''Embedded Base Boot Requirements''. Two specifications for ARM. If your target is in compliance with either, booting with UEFI should already be supported. With the minimal UEFI support in ''U-Boot'', targets that were not made to be EBBR compliant can be made compliant, or be close enough for what it matters.		Other than letter salads, they are ''Server Base Boot Requirements'' and ''Embedded Base Boot Requirements''. Two specifications for ARM. If your target is in compliance with either, booting with UEFI should already be supported. With the minimal UEFI support in ''U-Boot'', targets that were not made to be EBBR compliant can be made compliant, or be close enough for what it matters.

	== UEFI, on my SBC??? == <!--T:16-->		= UEFI, on my SBC??? = <!--T:16-->

	<!--T:17-->		<!--T:17-->
Line 60:		Line 60:
	Any other UEFI compliant ''Platform Firmware'' can be used.		Any other UEFI compliant ''Platform Firmware'' can be used.

	=== Getting the installer image (ISO) === <!--T:22-->		== Getting the installer image (ISO) === <!--T:22-->

	<!--T:23-->		<!--T:23-->
Line 66:		Line 66:

	<!--T:24-->		<!--T:24-->
	* [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.iso_minimal_new_kernel_no_zfs.aarch64-linux NixOS unstable, new kernel] – rolling release, latest mainline kernel, does not build with ZFS as it would often lag behind.		* [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.iso_minimal_new_kernel_no_zfs.aarch64-linux NixOS unstable, new kernel] – rolling release, latest mainline kernel, does not build with ZFS as it would often lag behind. (This image hasn't built in over a year as of August 2026, avoid using it)
	* [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.iso_minimal.aarch64-linux NixOS unstable, LTS kernel] – may be less compatible with specific hardware, but tracks a more recent Nixpkgs		* [https://hydra.nixos.org/job/nixos/trunk-combined/nixos.iso_minimal.aarch64-linux NixOS unstable, LTS kernel] – may be less compatible with specific hardware, but tracks a more recent Nixpkgs
	* [https://nixos.org/download.html#download-nixos NixOS stable] – release branch, LTS kernel, generally not recommended unless you are confident your hardware is well-supported upstream		* [https://nixos.org/download.html#download-nixos NixOS stable] – release branch, LTS kernel, generally not recommended unless you are confident your hardware is well-supported upstream
Line 131:		Line 131:
	</nowiki>}}		</nowiki>}}

	=== General Tips === <!--T:42-->		= General Tips = <!--T:42-->

	<!--T:43-->		<!--T:43-->
Line 143:		Line 143:
	</nowiki>}}		</nowiki>}}

	== Known Issues == <!--T:45-->		= Known Issues = <!--T:45-->

	=== Device Trees === <!--T:46-->		== Device Trees == <!--T:46-->

	<!--T:47-->		<!--T:47-->

Ryjelsum: /* Device Trees */ clarity to prev. edit

2026-08-22T03:35:34Z

Device Trees: clarity to prev. edit

← Older revision		Revision as of 03:35, 22 August 2026
Line 154:		Line 154:

	<!--T:49-->		<!--T:49-->
	With ''U-Boot'', it is possible to make it load a device tree, for example a more up-to-date one, by placing the dtb folder from a kernel build output at the <code>/dtb</code> location in the ESP. ''U-Boot'' will automatically load a device tree according to heuristics, which should be the right one. ~~This is~~ not ~~done~~ automatically, and may be potentially problematic when one wants to use NixOS <code>hardware.deviceTree.overlays</code> options - a rebuild will succeed, but the overlay will not be applied on the next boot.		With ''U-Boot'', it is possible to make it load a device tree, for example a more up-to-date one, by placing the dtb folder from a kernel build output at the <code>/dtb</code> location in the ESP. ''U-Boot'' will automatically load a device tree according to heuristics, which should be the right one. Device trees are not automatically copied to the ESP by NixOS, and this may be potentially problematic when one wants to use NixOS <code>hardware.deviceTree.overlays</code> options - a rebuild will succeed, but the overlay will not be applied on the next boot.

	<!--T:50-->		<!--T:50-->
	If one is using systemd-boot, this can be worked around by providing the device tree's full path to <code>hardware.deviceTree.name</code> - for example, <code>hardware.deviceTree.name = "rockchip/rk3328-rock64.dtb";</code> for a PINE64 ROCK64 board.		If one is using systemd-boot, this can be worked around by providing the device tree's full path to <code>hardware.deviceTree.name</code> - for example, <code>hardware.deviceTree.name = "rockchip/rk3328-rock64.dtb";</code> for a PINE64 ROCK64 board.
	</translate>		</translate>

Ryjelsum: /* Device Trees */ added info on problems with customized device trees/device tree overlays and EFI boot

2026-08-22T03:27:58Z

Device Trees: added info on problems with customized device trees/device tree overlays and EFI boot

← Older revision		Revision as of 03:27, 22 August 2026
Line 154:		Line 154:

	<!--T:49-->		<!--T:49-->
	With ''U-Boot'', it is possible to make it load a device tree, for example a more up-to-date one, by placing the dtb folder from a kernel build output at the <code>/dtb</code> location in the ESP. ''U-Boot'' will automatically load a device tree according to heuristics, which should be the right one.		With ''U-Boot'', it is possible to make it load a device tree, for example a more up-to-date one, by placing the dtb folder from a kernel build output at the <code>/dtb</code> location in the ESP. ''U-Boot'' will automatically load a device tree according to heuristics, which should be the right one. This is not done automatically, and may be potentially problematic when one wants to use NixOS <code>hardware.deviceTree.overlays</code> options - a rebuild will succeed, but the overlay will not be applied on the next boot.

	<!--T:50-->		<!--T:50-->
	It is ~~unknown how much of an actual issue~~ this ~~is in practice~~.		If one is using systemd-boot, this can be worked around by providing the device tree's full path to <code>hardware.deviceTree.name</code> - for example, <code>hardware.deviceTree.name = "rockchip/rk3328-rock64.dtb";</code> for a PINE64 ROCK64 board.
	</translate>		</translate>

Ardenet: Marked this version for translation

2025-10-07T22:41:37Z

Marked this version for translation

← Older revision		Revision as of 22:41, 7 October 2025
Line 54:		Line 54:
	As an opinionated example, you can get started with [https://github.com/Tow-Boot/Tow-Boot Tow-Boot, a ''U-Boot'' distribution], which is intended to make the initial setup a bit easier by abstracting the platform differences so that they do not matter.		As an opinionated example, you can get started with [https://github.com/Tow-Boot/Tow-Boot Tow-Boot, a ''U-Boot'' distribution], which is intended to make the initial setup a bit easier by abstracting the platform differences so that they do not matter.

			<!--T:51-->
	Where supported, Nix can be used to build U-boot from its main-line repositories. See [[U-Boot#Building a packaged U-Boot]] for further information. The resulting firmware image can then be flashed to SPI with tools such as <code>flashcp</code> or <code>flashrom</code>, or installed to EMMC/SD card by writing to specific offsets. This is platform specific, refer to [https://github.com/u-boot/u-boot/tree/master/doc/board upstream U-boot documentation for your platform or board].		Where supported, Nix can be used to build U-boot from its main-line repositories. See [[U-Boot#Building a packaged U-Boot]] for further information. The resulting firmware image can then be flashed to SPI with tools such as <code>flashcp</code> or <code>flashrom</code>, or installed to EMMC/SD card by writing to specific offsets. This is platform specific, refer to [https://github.com/u-boot/u-boot/tree/master/doc/board upstream U-boot documentation for your platform or board].

Ryjelsum: /* Getting a Platform Firmware */ more specificity

2025-07-19T14:56:47Z

Getting a Platform Firmware: more specificity

← Older revision		Revision as of 14:56, 19 July 2025
Line 54:		Line 54:
	As an opinionated example, you can get started with [https://github.com/Tow-Boot/Tow-Boot Tow-Boot, a ''U-Boot'' distribution], which is intended to make the initial setup a bit easier by abstracting the platform differences so that they do not matter.		As an opinionated example, you can get started with [https://github.com/Tow-Boot/Tow-Boot Tow-Boot, a ''U-Boot'' distribution], which is intended to make the initial setup a bit easier by abstracting the platform differences so that they do not matter.

	Where supported, Nix can be used to build U-boot from its main-line repositories. See [[U-Boot#Building a packaged U-Boot]] for further information. The resulting image can then be flashed to SPI with tools such as <code>flashcp</code> or <code>flashrom</code>, or installed to EMMC/SD card by writing to specific offsets. This is platform specific, refer to [https://github.com/u-boot/u-boot/tree/master/doc/board upstream U-boot documentation for your platform or board].		Where supported, Nix can be used to build U-boot from its main-line repositories. See [[U-Boot#Building a packaged U-Boot]] for further information. The resulting firmware image can then be flashed to SPI with tools such as <code>flashcp</code> or <code>flashrom</code>, or installed to EMMC/SD card by writing to specific offsets. This is platform specific, refer to [https://github.com/u-boot/u-boot/tree/master/doc/board upstream U-boot documentation for your platform or board].

	<!--T:21-->		<!--T:21-->

Ryjelsum: Added brief directions and reference links for building and flashing U-boot from Nixpkgs

2025-07-19T03:31:05Z

Added brief directions and reference links for building and flashing U-boot from Nixpkgs

← Older revision		Revision as of 03:31, 19 July 2025
Line 53:		Line 53:
	<!--T:20-->		<!--T:20-->
	As an opinionated example, you can get started with [https://github.com/Tow-Boot/Tow-Boot Tow-Boot, a ''U-Boot'' distribution], which is intended to make the initial setup a bit easier by abstracting the platform differences so that they do not matter.		As an opinionated example, you can get started with [https://github.com/Tow-Boot/Tow-Boot Tow-Boot, a ''U-Boot'' distribution], which is intended to make the initial setup a bit easier by abstracting the platform differences so that they do not matter.

			Where supported, Nix can be used to build U-boot from its main-line repositories. See [[U-Boot#Building a packaged U-Boot]] for further information. The resulting image can then be flashed to SPI with tools such as <code>flashcp</code> or <code>flashrom</code>, or installed to EMMC/SD card by writing to specific offsets. This is platform specific, refer to [https://github.com/u-boot/u-boot/tree/master/doc/board upstream U-boot documentation for your platform or board].

	<!--T:21-->		<!--T:21-->

Nicolas-goudry at 20:40, 12 July 2024

2024-07-12T20:40:17Z

← Older revision		Revision as of 20:40, 12 July 2024
Line 46:		Line 46:
	Believe me or not, it's more likely that you can, if your SBC is well supported by mainline ''[[U-Boot]]''. ''U-Boot'' provides enough UEFI to comply with EBBR, which in turn is enough to allow us to boot the <tt>AArch64</tt> UEFI NixOS iso, and with almost no differences compared to the <tt>x86_64</tt> guide, simply follow the installation instruction to boot into an installed system.		Believe me or not, it's more likely that you can, if your SBC is well supported by mainline ''[[U-Boot]]''. ''U-Boot'' provides enough UEFI to comply with EBBR, which in turn is enough to allow us to boot the <tt>AArch64</tt> UEFI NixOS iso, and with almost no differences compared to the <tt>x86_64</tt> guide, simply follow the installation instruction to boot into an installed system.

	=== Getting a ''Platform Firmware'' === <!--T:18-->		== Getting a ''Platform Firmware'' == <!--T:18-->

	<!--T:19-->		<!--T:19-->

Nicolas-goudry at 17:01, 12 July 2024

2024-07-12T17:01:20Z

← Older revision		Revision as of 17:01, 12 July 2024
Line 1:		Line 1:
	<~~language~~/>		<languages/>
	<translate>		<translate>
	<!--T:1-->		<!--T:1-->

Nicolas-goudry at 17:00, 12 July 2024

2024-07-12T17:00:52Z

← Older revision		Revision as of 17:00, 12 July 2024
Line 1:		Line 1:
			<language/>
	<translate>		<translate>
	<!--T:1-->		<!--T:1-->

Nicolas-goudry: Marked this version for translation

2024-07-12T15:31:59Z

Marked this version for translation

Show changes