nixos/doc/manual/installation/building-nixos.chapter.md

   1 # Building a NixOS (Live) ISO {#sec-building-image}
   2
   3 Default live installer configurations are available inside `nixos/modules/installer/cd-dvd`.
   4 For building other system images, see [Building Images with `nixos-rebuild build-image`](#sec-image-nixos-rebuild-build-image).
   5
   6 You have two options:
   7
   8 - Use any of those default configurations as is
   9 - Combine them with (any of) your host config(s)
  10
  11 System images, such as the live installer ones, know how to enforce configuration settings
  12 on which they immediately depend in order to work correctly.
  13
  14 However, if you are confident, you can opt to override those
  15 enforced values with `mkForce`.
  16
  17 ## Practical Instructions {#sec-building-image-instructions}
  18
  19 To 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
  28 To 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
  36 If you need additional (non-distributable) drivers or firmware in the
  37 installer, you might want to extend these configurations.
  38
  39 For example, to build the GNOME graphical installer ISO, but with support for
  40 certain WiFi adapters present in some MacBooks, you can create the following
  41 file 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
  56 Then 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
  67 The config value enforcement is implemented via `mkImageMediaOverride = mkOverride 60;`
  68 and therefore primes over simple value assignments, but also yields to `mkForce`.
  69
  70 This property allows image designers to implement in semantically correct ways those
  71 configuration values upon which the correct functioning of the image depends.
  72
  73 For example, the iso base image overrides those file systems which it needs at a minimum
  74 for correct functioning, while the installer base image overrides the entire file system
  75 layout because there can't be any other guarantees on a live medium than those given
  76 by the live medium itself. The latter is especially true before formatting the target
  77 block device(s). On the other hand, the netboot iso only overrides its minimum dependencies
  78 since netboot images are always made-to-target.