NixVirt

The nixosModules.default output provides a NixOS module to manage libvirt.

Available Options:

• virtualisation.libvirt.enable (bool, default false): Enables NixVirt. This also enables virtualisation.libvirtd.enable and sets virtualisation.libvirtd.package.
• virtualisation.libvirt.package (package, default packages.libvirt): The libvirt package to use. This also sets virtualisation.libvirtd.package.
• virtualisation.libvirt.verbose (bool, default false): Enables an output trace of changes during activation, useful for debugging domain changes.
• virtualisation.libvirt.swtpm.enable (bool, default false): Enables the software TPM emulator (swtpm).
• virtualisation.libvirt.connections.<connection> (set): Configuration for a specific hypervisor connection URI (e.g., "qemu:///system").

Connection Attributes:

• domains (list of sets): Defines libvirt domains.
  • definition (path): Path to the domain XML.
  • active (bool or null): Target state (running/stopped).
  • restart (bool or null): Whether to restart the domain.
  • Warning: Specifying this list will cause any libvirt domain not in the list to be deleted (though volumes/NVRAM/TPM state are preserved).
• networks (list of sets): Defines libvirt networks.
  • definition (path): Path to the network XML.
  • active (bool or null): Target state.
  • restart (bool or null): Whether to restart.
  • Warning: Specifying this list will cause any libvirt network not in the list to be deleted.
• pools (list of sets): Defines libvirt storage pools.
  • definition (path): Path to the pool XML.
  • active (bool or null): Target state.
  • restart (bool or null): Whether to restart.
  • volumes (list of sets): Volumes to manage.
    • present (bool, default true): Whether the volume should exist.
    • definition (path, default null): Path to volume XML.
    • name (string, default null): Volume name (required if present = false).
  • Warning: Specifying this list will cause any libvirt pool not in the list to be deleted (files/storage are preserved).

Note: NixOS already has virtualisation.libvirtd options for the daemon itself.

The lib.domain API allows you to generate libvirt domain XML from Nix structures.

• lib.domain.getXML: Returns a string containing the domain XML.
• lib.domain.writeXML: Returns a path to a file containing the domain XML.
• lib.domain.templates: Provides pre-configured templates for common use cases.

Domain Templates

lib.domain.templates.linux

Suitable for Linux guests. Arguments: name (required), uuid (required), memory (default { count = 4; unit = "GiB"; }), storage_vol, backing_vol, install_vol, bridge_name (default "virbr0"), virtio_net, virtio_video, virtio_drive.

lib.domain.templates.windows

Suitable for Windows 11 guests. Supports Secure Boot (via OVMF) and emulated TPM (requires virtualisation.libvirt.swtpm.enable = true). Arguments: name (required), uuid (required), memory, storage_vol, backing_vol, install_vol, bridge_name, nvram_path (required), virtio_net, virtio_video, virtio_drive, install_virtio (adds a CDROM with VirtIO drivers).

lib.domain.templates.pc and lib.domain.templates.q35

Basic Intel machine templates (440FX and Q35 respectively).

# Example: Creating a Linux domain in Home Manager
virtualisation.libvirt.connections."qemu:///session".domains = [
  {
    definition = nixvirt.lib.domain.writeXML (nixvirt.lib.domain.templates.linux
      {
        name = "Penguin";
        uuid = "cc7439ed-36af-4696-a6f2-1f0c4474d87e";
        memory = { count = 6; unit = "GiB"; };
        storage_vol = { pool = "MyPool"; volume = "Penguin.qcow2"; }
        backing_vol = /home/ashley/VM-Storage/Base.qcow2;
      });
  }
];

The lib.network API allows you to generate libvirt network XML.

• lib.network.getXML: Returns a string containing the network XML.
• lib.network.writeXML: Returns a path to a file containing the network XML.
• lib.network.templates.bridge: A template for a typical bridge used in qemu:///system so that qemu:///session domains can connect to it.

lib.network.templates.bridge Arguments:

• name (default "default")
• uuid (required)
• bridge_name (default "virbr0")
• subnet_byte (required, integer 1-254): Sets the subnet to 192.168.x.0/24 where x is the subnet_byte.

# Example: Creating a bridge network in NixOS
virtualisation.libvirt.connections."qemu:///system".networks = [
  {
    definition = nixvirt.lib.network.writeXML (nixvirt.lib.network.templates.bridge
      {
        uuid = "70b08691-28dc-4b47-90a1-45bbeac9ab5a";
        subnet_byte = 71;
      });
    active = true;
  }
];

virtdeclare is a command-line tool used to define and control libvirt objects (domains and networks) idempotently. It is the underlying tool used by the Nix modules.

Usage:

usage: virtdeclare [-h] [-v] --connect URI --type {domain,network} (--define PATH | --uuid ID | --name ID) [--state {active,inactive}] [--auto]

Options:

• --connect URI: Connection URI (e.g., qemu:///session).
• --type {domain,network}: The object type.
• --define PATH: Path to the XML definition file.
• --uuid ID: Object UUID.
• --name ID: Object name.
• --state {active,inactive}: Target state.
• --auto: Set autostart to match the state.
• -v, --verbose: Report actions to stderr.

Behavior:

• Redefining an object with a different definition will trigger a restart if the object is active (unless --state inactive is specified).
• Deactivating a domain immediately terminates it (equivalent to pulling the power).
• Currently only supports domain and network types.

virtdeclare --connect qemu:///session --type domain --define /path/to/domain.xml --state active