Convert a Proxmox VM to a Template: Full Guide with Cloud-Init

Why Use VM Templates

Creating VMs from scratch every time is slow and error-prone. A Proxmox VM template is a read-only base image that you clone to create new VMs in seconds. Templates ensure consistency across deployments, reduce storage when using linked clones, and integrate with cloud-init for automatic hostname, network, and SSH key configuration at first boot.

Step 1: Prepare the VM for Templating

Before converting a VM to a template, you need to remove machine-specific data so that each clone gets a unique identity. Skipping this step leads to duplicate SSH host keys, conflicting machine IDs, and DHCP issues.

# SSH into the VM you want to template (e.g., a Debian 12 VM)
# Run these commands inside the guest

# Remove SSH host keys (regenerated on first boot)
rm -f /etc/ssh/ssh_host_*

# Truncate machine-id (systemd regenerates it on boot)
truncate -s 0 /etc/machine-id
rm -f /var/lib/dbus/machine-id

# Clean apt cache to reduce template size
apt clean
apt autoremove -y

# Remove user shell history
rm -f /root/.bash_history
rm -f /home/*/.bash_history

# Clear log files
truncate -s 0 /var/log/*.log
truncate -s 0 /var/log/**/*.log 2>/dev/null
journalctl --vacuum-time=0

# Remove temporary files
rm -rf /tmp/*
rm -rf /var/tmp/*

# If using DHCP, remove cached leases so the clone gets a new IP
rm -f /var/lib/dhcp/*.leases

# Optional: remove user accounts (if template should be generic)
# userdel -r myuser

# Shutdown the VM cleanly
shutdown -h now

Step 2: Convert the VM to a Template

Once the VM is powered off and cleaned, convert it to a template from the Proxmox host.

# Verify the VM is stopped
qm status 9000
# Expected: status: stopped

# Convert to template (this is irreversible!)
qm template 9000

# The VM icon in the Proxmox UI changes to a template icon
# You can no longer start, modify disks, or snapshot the template
# The only operations available are: clone, remove, and edit description

# Verify it's now a template
qm config 9000 | grep template
# template: 1

Warning: Converting to a template is a one-way operation. You cannot convert a template back to a regular VM. Always keep notes about how the template was built so you can recreate it if needed.

Step 3: Clone the Template

Proxmox supports two clone modes: full clone and linked clone. Each has different storage and performance characteristics.

# Full clone: independent copy of all disks
# Pros: no dependency on template, can be moved to different storage
# Cons: uses full disk space, slower to create
qm clone 9000 101 --name web-server-01 --full true
qm clone 9000 102 --name web-server-02 --full true

# Linked clone: uses template as a read-only base, stores only differences
# Pros: instant creation, minimal initial disk usage
# Cons: depends on template (don't delete it), same storage only
qm clone 9000 201 --name dev-server-01 --full false
qm clone 9000 202 --name dev-server-02 --full false

# Check disk usage difference
pvesh get /nodes/pve/storage/local-lvm/content --output-format json | \
    jq '.[] | {volid: .volid, size: (.size/1073741824)}'

For development and testing, linked clones are excellent since you can spin up dozens of instances quickly. For production, full clones are safer because they have no dependency on the template.

Adding Cloud-Init Support

Cloud-init allows you to configure hostname, network, SSH keys, and run custom scripts automatically when a clone first boots. This eliminates the need to log into each new VM to configure it.

# Before converting to template, add a cloud-init drive
qm set 9000 --ide2 local-lvm:cloudinit

# Install cloud-init inside the VM (before templating)
# SSH into the VM:
apt install -y cloud-init

# Enable cloud-init services
systemctl enable cloud-init-local
systemctl enable cloud-init
systemctl enable cloud-config
systemctl enable cloud-final

# Configure cloud-init data source for Proxmox
cat > /etc/cloud/cloud.cfg.d/99-proxmox.cfg << 'CLOUDCFG'
datasource_list: [NoCloud, ConfigDrive]
CLOUDCFG

# Shutdown, then convert to template on the Proxmox host
shutdown -h now

After creating the template, set default cloud-init parameters that clones will inherit:

# Set cloud-init defaults on the template
qm set 9000 --ciuser admin
qm set 9000 --sshkeys ~/.ssh/id_rsa.pub
qm set 9000 --ipconfig0 ip=dhcp
qm set 9000 --cipassword "temporary-password"
qm set 9000 --nameserver 1.1.1.1
qm set 9000 --searchdomain example.com

# When cloning, override per-instance settings
qm clone 9000 103 --name prod-db-01 --full true
qm set 103 --ipconfig0 ip=192.168.1.50/24,gw=192.168.1.1
qm set 103 --ciuser dbadmin
qm set 103 --nameserver 192.168.1.1

# Start the clone - cloud-init runs automatically on first boot
qm start 103

# Verify cloud-init completed inside the VM
cloud-init status
# status: done

Template Best Practices

• Use a high VM ID for templates (e.g., 9000-9099) to keep them visually separated from regular VMs in the UI.
• Include the OS and date in the template name: debian12-base-2026-04.
• Keep templates updated by cloning, updating, cleaning, and creating a new template periodically.
• Use a minimal OS install for the template. Add application-specific packages after cloning.
• Install qemu-guest-agent in the template so all clones report accurate status to Proxmox.

# Recommended template VM configuration
qm create 9000 --name debian12-template --memory 1024 --cores 2 \
    --net0 virtio,bridge=vmbr0 \
    --scsihw virtio-scsi-single \
    --scsi0 local-lvm:10 \
    --ide2 local-lvm:cloudinit \
    --boot order=scsi0 \
    --agent enabled=1 \
    --serial0 socket \
    --vga serial0

Once you have templates set up, deploying new infrastructure becomes fast and repeatable. If you manage your Proxmox environment through ProxmoxR, you can see all your templates and clones organized together, making it easy to track which VMs were created from which base image.