nixpkgs/doc/build-helpers/special/vm-tools.section.md

vmTools

A set of VM related utilities, that help in building some packages in more advanced scenarios.

vmTools.createEmptyImage

A bash script fragment that produces a disk image at destination.

Attributes

• size. The disk size, in MiB.
• fullName. Name that will be written to ${destination}/nix-support/full-name.
• destination (optional, default $out). Where to write the image files.

vmTools.runInLinuxVM

Run a derivation in a Linux virtual machine (using Qemu/KVM). By default, there is no disk image; the root filesystem is a tmpfs, and the Nix store is shared with the host (via the 9P protocol). Thus, any pure Nix derivation should run unmodified.

If the build fails and Nix is run with the -K/--keep-failed option, a script run-vm will be left behind in the temporary build directory that allows you to boot into the VM and debug it interactively.

Attributes

• preVM (optional). Shell command to be evaluated before the VM is started (i.e., on the host).
• memSize (optional, default 512). The memory size of the VM in MiB (1024×1024 bytes).
• diskImage (optional). A file system image to be attached to /dev/sda. Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.

Examples

Build the derivation hello inside a VM:

{ pkgs }: with pkgs; with vmTools; runInLinuxVM hello

Build inside a VM with extra memory:

{ pkgs }:
with pkgs;
with vmTools;
runInLinuxVM (
  hello.overrideAttrs (_: {
    memSize = 1024;
  })
)

Use VM with a disk image (implicitly sets diskImage, see vmTools.createEmptyImage):

{ pkgs }:
with pkgs;
with vmTools;
runInLinuxVM (
  hello.overrideAttrs (_: {
    preVM = createEmptyImage {
      size = 1024;
      fullName = "vm-image";
    };
  })
)

vmTools.extractFs

Takes a file, such as an ISO, and extracts its contents into the store.

Attributes

• file. Path to the file to be extracted. Note that currently we expect the image to contain a filesystem, not a full disk image with a partition table etc.
• fs (optional). Filesystem of the contents of the file.

Examples

Extract the contents of an ISO file:

{ pkgs }: with pkgs; with vmTools; extractFs { file = ./image.iso; }

vmTools.extractMTDfs

Like , but it makes use of a Memory Technology Device (MTD).

vmTools.runInLinuxImage

Like , but instead of using stdenv from the Nix store, run the build using the tools provided by /bin, /usr/bin, etc. from the specified filesystem image, which typically is a filesystem containing a FHS-based Linux distribution.

vmTools.makeImageTestScript

Generate a script that can be used to run an interactive session in the given image.

Examples

Create a script for running a Fedora 43 VM:

{ pkgs }: pkgs.vmTools.makeImageTestScript pkgs.vmTools.diskImages.fedora43x86_64

Create a script for running an Ubuntu 24.04 VM:

{ pkgs }: pkgs.vmTools.makeImageTestScript pkgs.vmTools.diskImages.ubuntu2404x86_64

vmTools.diskImageFuns

A set of functions that build a predefined set of minimal Linux distributions images.

Images

• Fedora
  • fedora42x86_64
  • fedora43x86_64
• Rocky Linux
  • rocky9x86_64
  • rocky10x86_64
• AlmaLinux
  • alma9x86_64
  • alma10x86_64
• Oracle Linux
  • oracle9x86_64
• Amazon Linux
  • amazon2023x86_64
• Ubuntu
  • ubuntu2204i386
  • ubuntu2204x86_64
  • ubuntu2404x86_64
• Debian
  • debian11i386
  • debian11x86_64
  • debian12i386
  • debian12x86_64
  • debian13i386
  • debian13x86_64

Attributes

• size (optional, defaults to 4096). The size of the image, in MiB.
• extraPackages (optional). A list of names of additional packages from the distribution that should be included in the image.

Examples

8GiB image containing Firefox in addition to the default packages:

{ pkgs }:
pkgs.vmTools.diskImageFuns.ubuntu2404x86_64 {
  extraPackages = [ "firefox" ];
  size = 8192;
}

vmTools.diskImageExtraFuns

Shorthand for vmTools.diskImageFuns.<attr> { extraPackages = ... }.

vmTools.diskImages

Shorthand for vmTools.diskImageFuns.<attr> { }.