pyrox.dev
1# Building a NixOS (Live) ISO {#sec-building-image}
2
3Default live installer configurations are available inside `nixos/modules/installer/cd-dvd`.
4For building other system images, see [Building Images with `nixos-rebuild build-image`](#sec-image-nixos-rebuild-build-image).
5
6You have two options:
7
8- Use any of those default configurations as is
9- Combine them with (any of) your host config(s)
10
11System images, such as the live installer ones, know how to enforce configuration settings
12on which they immediately depend in order to work correctly.
13
14However, if you are confident, you can opt to override those
15enforced values with `mkForce`.
16
17## Practical Instructions {#sec-building-image-instructions}
18
19To build an ISO image for the channel `nixos-unstable`:
20
21```ShellSession
22$ git clone https://github.com/NixOS/nixpkgs.git
23$ cd nixpkgs/nixos
24$ git switch nixos-unstable
25$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix
26```
27
28To check the content of an ISO image, mount it like so:
29
30```ShellSession
31# mount -o loop -t iso9660 ./result/iso/nixos-image-25.05pre-git-x86_64-linux.iso /mnt/iso
32```
33
34## Additional drivers or firmware {#sec-building-image-drivers}
35
36If you need additional (non-distributable) drivers or firmware in the
37installer, you might want to extend these configurations.
38
39For example, to build the GNOME graphical installer ISO, but with support for
40certain WiFi adapters present in some MacBooks, you can create the following
41file at `modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix`:
42
43```nix
44{ config, ... }:
45
46{
47 imports = [ ./installation-cd-graphical-gnome.nix ];
48
49 boot.initrd.kernelModules = [ "wl" ];
50
51 boot.kernelModules = [ "kvm-intel" "wl" ];
52 boot.extraModulePackages = [ config.boot.kernelPackages.broadcom_sta ];
53}
54```
55
56Then build it like in the example above:
57
58```ShellSession
59$ git clone https://github.com/NixOS/nixpkgs.git
60$ cd nixpkgs/nixos
61$ export NIXPKGS_ALLOW_UNFREE=1
62$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-graphical-gnome-macbook.nix default.nix
63```
64
65## Technical Notes {#sec-building-image-tech-notes}
66
67The config value enforcement is implemented via `mkImageMediaOverride = mkOverride 60;`
68and therefore primes over simple value assignments, but also yields to `mkForce`.
69
70This property allows image designers to implement in semantically correct ways those
71configuration values upon which the correct functioning of the image depends.
72
73For example, the iso base image overrides those file systems which it needs at a minimum
74for correct functioning, while the installer base image overrides the entire file system
75layout because there can't be any other guarantees on a live medium than those given
76by the live medium itself. The latter is especially true before formatting the target
77block device(s). On the other hand, the netboot iso only overrides its minimum dependencies
78since netboot images are always made-to-target.