Skip to content

Introduction and quick-start

Nvirt is a tool for repeatably provisioning libvirt virtual machines. Define customisations for your OS, and easily set up features like port forwarding and shared volumes.

It's similar to having a 'containerfile' or 'dockerfile', but for a libvirt VM instead of a container.

GitLab: nvirt-cli/nvirt

Behind the scenes, nvirt is mostly a declarative-ish wrapper around the wonderful tools provided by the libguestfs project (virt-builder and virt-customize) and the virt-manager project (virt-install), with a few extra conveniences around the edges.

Note

Nvirt currently only creates libvirt user-session virtual machines. But with shared volumes and port forwarding, it's functional and has the advantage of not requiring system privileges by default.

Commands

  • nvirt init - Create a new virtfile from a template.
  • nvirt up - Start the machine defined in the virtfile.
  • nvirt ssh - Open an SSH session in the machine.
  • nvirt sshinfo - Get information about the SSH connection (IP, port, identity key).
  • nvirt halt - Shut down the machine.
  • nvirt destroy - Delete the VM and its backing disk(s).

Quick-start: Using a virt-builder image template

This example builds a new VM based on the virt-builder fedora-42 image, installs an nginx web server, and sets up port-forwarding for it and a bi-directional shared folder mounted at /shared in the guest.

  • Copy the following text into a file called virtfile in a new directory
  • Run nvirt up from inside that directory.
  • Once it's booted, you can browse to http://localhost:8080/ to interact with the nginx web server running inside.

Example virtfile: Based on virt-builder Fedora 42, with an nginx web server

virtfile
source: virt-builder
image: fedora-42  # see `virt-builder --list` for available templates


# the 'customize' section allows you to configure the OS image before first boot.
#
# when the source is virt-builder (as above), all lines in this section map
# directly to options for the virt-builder command - see its manual for a full list.

customize:
  - size: 40G
  - install: openssh-server,nginx


# the 'machine' section allows you to configure the virtual machine itself.
#
# all lines in this section map directly to options for the virt-install command. 
# see its manual for a full list.

machine:
  - osinfo: linux2024
  - vcpu: 2
  - memory: 3072


# the sections below are entirely optional and only for demonstration.
# details available in the docs.

ports:
  - 127.0.0.1:8080:80  # forward port 8080 on the host to port 80 in the guest

volumes:
  - .:/shared:rw

Quick-start: Using a distribution image with virt-customize

Many distributions provide pre-built "cloud images" that can be used directly. If you have a URL for an image that you want to use for your VM, you can specify the url source.

  • Copy the following text into a file called virtfile in a new directory
  • Run nvirt up from inside that directory.
  • Once it's booted, you can browse to http://localhost:8081/ to interact with the nginx web server running inside.

Example virtfile: Based on Debian 13 upstream image, with an nginx web server

virtfile
source: url
image: https://cloud.debian.org/images/cloud/trixie/latest/debian-13-nocloud-amd64.qcow2
resize: 40G


# the 'customize' section allows you to configure the OS image before first boot.
#
# for the 'url' source, all lines in the 'customize' section map directly to
# options for the virt-customize command - see its manual for a full list.

customize:
  - install: openssh-server,cloud-guest-utils,nginx
  - run-command: growpart /dev/sda 1


# the 'machine' section allows you to configure of the virtual machine itself.
#
# all lines in this section map directly to options for the virt-install command.
# see its manual for a full list.

machine:
  - osinfo: debian13
  - vcpu: 2
  - memory: 2048
  - boot: uefi


# the sections below are entirely optional and only for demonstration.
# details available in the docs.

ssh:
  type: vsock

ports:
  - 127.0.0.1:8081:80

volumes:
  - .:/shared:rw

Note

When specifying a disk size with the 'url' source and the 'resize' option, only the virtual disk itself is resized. You may need to specify extra commands to expand the partitions and filesystems it contains.

The growpart tool is used in this example to expand the root partition (partition 1 in this case).