qm-template

A Python CLI that downloads cloud images and creates Proxmox VE VM templates with Cloud-Init support.

Features

• Multi-distro downloads: Debian, Ubuntu, Rocky Linux, AlmaLinux, Fedora, CentOS Stream, Alpine, openSUSE and Arch Linux
• Checksum verification: SHA-256/SHA-512 fetched from each distro's official checksum files and saved next to the image (<image>.sha256/.sha512)
• Pinned builds: dated builds are selected where the upstream offers them, and images mirror the upstream directory layout
• Resumable downloads: uses axel, aria2c, wget or curl, whichever is available, with a configurable number of parallel connections
• Complete qm create command: the whole template is assembled into a single qm create ... --template 1 invocation instead of a chain of qm set calls
• TOML configuration: read with tomllib from the standard library
• Standard library only: Python >= 3.11; external commands are limited to the downloader and the Proxmox VE qm/pvesm tools

Requirements

• Python >= 3.11
• uv to install and develop
• A Proxmox VE host, normally running as root
• Proxmox VE (qm, pvesm) for the create command
• One of axel, aria2c, wget or curl for the download command

Installation

Install the CLI as a uv tool:

uv tool install qm-template

For development, sync the project and run it from the virtual environment:

uv sync --group dev
uv run qm-template --help

Configuration

The configuration file is optional and loaded from /etc/qm-template/config.toml. It is created with the built-in defaults on first run; use --config PATH or QM_TEMPLATE_CONFIG to point elsewhere. Downloaded images are stored in /var/lib/qm-template unless paths.images_dir overrides it, mirroring the upstream layout:

<images_dir>/<distro>/<release>/[<tag>/]<filename>

download.preferred orders the downloaders and download.connections sets the number of parallel connections for axel and aria2c. create.sshkeys lists inline SSH public keys and create.sshkeys_files lists key files; the contents of both are merged and deduplicated by key fingerprint for Cloud-Init, and at least one key is required. To create the file manually instead:

install -d /etc/qm-template
cp qm-template.example.toml /etc/qm-template/config.toml

Command-line options override the configured defaults.

Usage

Download a cloud image

# default distro from the configuration file
qm-template download

# pick a distro, optionally override parameters
qm-template download debian
qm-template download ubuntu --release noble --variant minimal
qm-template download debian --release bookworm --tag 20260907-2594

# print the first available downloader's command without running it
qm-template download --dry-run alpine

# list distros and their configured defaults
qm-template distros

--dry-run resolves the image and pretty prints the command of the first available downloader, one argument group per line, without downloading anything. Builds are pinned where the upstream provides dated snapshots (Debian, Ubuntu server, Arch Linux, openSUSE Tumbleweed): the newest build is selected, and a newer build is downloaded alongside the old one instead of overwriting it. Interrupted downloads are resumed on the next run; partial files are stored as <image>.part. The checksum fetched from the upstream source is saved next to the image as <image>.sha256 or <image>.sha512, depending on the upstream algorithm.

Create a VM template

# interactive image and VM ID selection
qm-template create

# filter images with a regular expression on the relative path
qm-template create debian-13

# non-interactive
qm-template create --vm-id 9000 --vm-name debian-13-template

# inspect the assembled command without running it
qm-template create --dry-run --vm-id 9000

The resulting command is a single qm create invocation, which --dry-run pretty prints as:

qm create 9000 \
    --name debian-13-template \
    --cpu cputype=host \
    --cores 1 \
    --balloon 1024 \
    --memory 1024 \
    --net0 model=virtio,firewall=1,bridge=vmbr0 \
    --scsihw virtio-scsi-single \
    --agent type=virtio,enabled=1 \
    --machine q35 \
    --ostype l26 \
    --serial0 socket \
    --vga serial0 \
    --scsi0 local-lvm:0,import-from=/path/to/image.qcow2 \
    --scsi1 local-lvm:cloudinit \
    --boot order=scsi0 \
    --ipconfig0 ip=dhcp \
    --ciupgrade 0 \
    --ciuser debian \
    --cipassword debian \
    --sshkeys ~/.ssh/id_ed25519.pub \
    --template 1

Supported distros

Development

uv sync --group dev
just lint        # ruff check --fix + ruff format
just typecheck   # ty check src/
just test        # pytest
just docs-build  # mkdocs build

Project layout:

qm-template/
├── pyproject.toml
├── qm-template.example.toml
├── src/qm_template/
│   ├── cli.py          # argument parsing and entry point
│   ├── commands.py     # download / create / distros commands
│   ├── config.py       # TOML settings and first-run config seeding
│   ├── checksum.py     # checksum parsing and verification
│   ├── config.default.toml  # default configuration shipped in the wheel
│   ├── download.py     # axel / aria2c / wget / curl wrappers
│   ├── http.py         # HTTP helpers and directory listings
│   ├── log.py          # logging setup
│   ├── pve.py          # qm/pvesm integration
│   ├── shell.py        # grouped command rendering and execution
│   └── distros/        # one module per distro family
└── tests/

Documentation

The published documentation site lives at https://ak1ra-lab.github.io/qm-template/.

References

• Proxmox VE Cloud-Init Support
• Debian Cloud Images
• Ubuntu Cloud Images