Home • Explore • Blog • Models • CI
☰



nixpkgs
1st chunk of `doc/build-helpers/images/makediskimage.section.md`
ec91901e1eb1de8502dbf77797289242170e52aad80143b7000000010000090b
# `<nixpkgs/nixos/lib/make-disk-image.nix>` {#sec-make-disk-image}

`<nixpkgs/nixos/lib/make-disk-image.nix>` is a function to create _disk images_ in multiple formats: raw, QCOW2 (QEMU), QCOW2-Compressed (compressed version), VDI (VirtualBox), VPC (VirtualPC).

This function can create images in two ways:

- using `cptofs` without any virtual machine to create a Nix store disk image,
- using a virtual machine to create a full NixOS installation.

When testing early-boot or lifecycle parts of NixOS such as a bootloader or multiple generations, it is necessary to opt for a full NixOS system installation.
Whereas for many web servers, applications, it is possible to work with a Nix store only disk image and is faster to build.

NixOS tests also use this function when preparing the VM. The `cptofs` method is used when `virtualisation.useBootLoader` is false (the default). Otherwise the second method is used.

## Features {#sec-make-disk-image-features}

For reference, read the function signature source code for documentation on arguments: <https://github.com/NixOS/nixpkgs/blob/master/nixos/lib/make-disk-image.nix>.
Features are separated in various sections depending on if you opt for a Nix-store only image or a full NixOS image.

### Common {#sec-make-disk-image-features-common}

- arbitrary NixOS configuration
- automatic or bound disk size: `diskSize` parameter, `additionalSpace` can be set when `diskSize` is `auto` to add a constant of disk space
- multiple partition table layouts: EFI, legacy, legacy + GPT, hybrid, none through `partitionTableType` parameter
- OVMF or EFI firmwares and variables templates can be customized
- root filesystem `fsType` can be customized to whatever `mkfs.${fsType}` exists during operations
- root filesystem label can be customized, defaults to `nix-store` if it's a Nix store image, otherwise `nixpkgs/nixos`
- arbitrary code can be executed after disk image was produced with `postVM`
- the current nixpkgs can be realized as a channel in the disk image, which will change the hash of the image when the sources are updated
- additional store paths can be provided through `additionalPaths`

### Full NixOS image {#sec-make-disk-image-features-full-image}

- arbitrary contents with permissions can be placed in the target filesystem using `contents`
Title: NixOS Disk Image Creation with `make-disk-image.nix`
Summary
The `make-disk-image.nix` function in Nixpkgs is used to create disk images in various formats (e.g., raw, QCOW2, VDI, VPC). It offers two primary methods: a faster 'Nix store only' image using `cptofs` (suitable for applications like web servers, and used by default in NixOS tests when `virtualisation.useBootLoader` is false) and a 'full NixOS installation' image that utilizes a virtual machine (necessary for testing early-boot or lifecycle parts of NixOS). Key features include support for arbitrary NixOS configurations, customizable disk size, multiple partition table layouts, configurable root filesystem types and labels, firmware customization, post-image creation execution (`postVM`), and the ability to include additional store paths. Full NixOS images also allow for placing arbitrary contents with permissions.