Skip to content

PVE Template Builder

PVE Template Builder creates VM templates in a Proxmox Virtual Environment cluster. It takes a YAML specification file describing how to build a disk image — packages to install, configuration adjustments, and shell-based customizations — and how to publish the result as a template VM, and does the rest: bootstrapping the OS with debootstrap, running the build steps in a chroot, converting the image, and creating the template via the PVE API.

See How a Template Is Built for the full sequence and host requirements, and Specification File Reference for every option in the spec file.

Quick start

  1. Install pve-template-builder and the tools it needs at build time. Download a release for Linux/amd64 — currently the only platform built — from Releases. The .deb is the easiest path: installing it also pulls in every required tool automatically, via the package's own apt dependencies:

    apt install ./pve-template-builder-<version>-amd64.deb

    With the .tar.gz release, or building from source (go build ., Go 1.26+), install those tools yourself instead:

    apt install debootstrap gdisk dosfstools e2fsprogs qemu-utils apt-move apt-utils

    See Requirements for the full list, including what's needed for non-ext4 filesystems and for bootstrapping a different distribution than the build host's own.

  2. Write a spec file, or start from one of the examples in example-specs/ — debian.yaml and ubuntu.yaml both use the built-in debian-serial/ ubuntu-serial presets (see Presets) to get a bootable, serial-console VM template with only a few fields of your own. example.yaml in the same directory isn't meant to be built — it's a syntax reference showing every step kind in one file; see builder.steps.

  3. Build and publish it:

    sudo pve-template-builder spec.yaml

    pve-template-builder must run as root — creating nbd devices, mounting filesystems, and chrooting all require it.

  4. Or validate a spec file without building anything:

    pve-template-builder -dry-run spec.yaml

Design notes

  • One preset, one boot setup: debian-serial and ubuntu-serial prepend the same shared boot-setup step to builder.steps — a spec using a preset only needs to describe what makes that image different. See Presets.
  • No host mutation: everything happens inside a loop-mounted disk image and a chroot; the build host's own package state and filesystem are never touched.

For the reasoning behind these and other non-obvious choices, see Design Notes.