disko

Use disko-install to automate partitioning and NixOS installation on a target disk. This is useful for fresh installations or creating bootable USB sticks from a workstation.

Requirements:

• A Linux system with Nix installed.
• A target disk or partition.
• A Nix flake defining your NixOS configuration.

Workflow:

1. Generate a base configuration using nixos-generate-config --root /tmp/config --no-filesystems.
2. Edit configuration.nix and create a flake.nix in /tmp/config/etc/nixos that includes disko.nixosModules.disko and your disko.devices definition.
3. Identify your target device using lsblk.
4. Run the disko-install command via nix run.

sudo nix run 'github:nix-community/disko/latest#disko-install' -- --flake <flake-url>#<flake-attr> --disk <disk-name> <disk-device>

Add the disko channel as root and update your channels. Then, import the module using the <disko/module.nix> syntax in your configuration.nix.

nix-channel --add https://github.com/nix-community/disko/archive/master.tar.gz disko
nix-channel --update

{
  imports = [ <disko/module.nix> ];
}

You can run disko directly from the nix-community repository without manual installation. To apply a configuration file to a specific disk, use the nix run command with the appropriate --mode flags. Common modes include destroy, format, and mount.

sudo nix --experimental-features "nix-command flakes" run github:nix-community/disko/latest -- --mode destroy,format,mount /tmp/disk-config.nix

Alternatively, you can build the image directly inside the Nix store instead of using the diskoImagesScript.

Warning: This method is slower because it requires copying the image after the build, and it does not provide a secure way to embed secrets via --pre-format-files.

nix build .#nixosConfigurations.myhost.config.system.build.diskoImages

Disko provides an interactive VM runner similar to config.system.build.vm. To run an interactive VM for a specific NixOS configuration, use the vmWithDisko attribute from the system.build set.

Note that the VM's image size is determined by your disko.devices.disk.<name>.imageSize specifications, and the memory size is controlled by disko.memSize.

nix run -L '.#nixosConfigurations.mymachine.config.system.build.vmWithDisko'

If you need to debug a test or inspect the VM state manually, you can build an interactive test driver and run it in an IPython prompt. This allows you to step through the test script and inspect the machine state after specific operations like disko-format or disko-mount.

1. Build the interactive driver:

   nix build .#checks.x86_64-linux.simple-efi.driverInteractive

2. Run the driver:

   result/bin/nixos-test-driver --keep-vm-state

3. Interact with the VM: Once in the IPython prompt, use machine.shell_interact() to attach a terminal to the VM. This opens a QEMU window. To return to the IPython prompt from the VM shell, press Ctrl+D.

If you use Nix Flakes, add disko as an input and ensure its nixpkgs input follows your system's nixpkgs. Include disko.nixosModules.disko in your modules list within your NixOS configuration.

{
  inputs.disko.url = "github:nix-community/disko/latest";
  inputs.disko.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { self, nixpkgs, disko }: {
    # change `yourhostname` to your actual hostname
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      # change to your system:
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        disko.nixosModules.disko
      ];
    };
  };
}

The disko CLI can be used to apply disk configurations from either a local .nix file or a Nix flake.

When using flakes, disko looks for the configuration in the .diskoConfigurations top-level attribute. If not found there, it searches for a disko module within a NixOS configuration of the same name under .nixosConfigurations.

Basic Usage Patterns:

• Local file: ./disko [options] disk-config.nix
• Flake: ./disko [options] --flake github:somebody/somewhere#disk-config

To run a specific test suite, use nix build targeting the specific check attribute. For example, to run the simple-efi test, use the command below. This process builds a VM, connects virtual disks based on the configuration, runs disko to format them, reboots, and then executes the extraTestScript to verify partitions and mount points.

nix build --no-link .#checks.x86_64-linux.simple-efi

Add disko to npins, then use the sources object in your configuration.nix to import the module.

npins add github nix-community disko

let
  sources = import ./npins;
in
{
  imports = [ (sources.disko + "/module.nix") ];
  …
}