How to back up Proxmox VE virtual machines

What you will set up

BackupZit backs up Proxmox VE virtual machines (QEMU) and containers (LXC) without installing anything inside the guests. A small agent runs on each Proxmox node, takes a temporary snapshot of every guest, reads its disks and stores them on the storage you choose. A web console schedules the jobs, keeps the history and runs the restores.

• What you need
• 1. Console
• 2. Storage
• 3. Agent on the node
• 4. Backup job
• 5. Consistent backups
• 6. Off-site copy
• 7. Restore tests
• Restoring
• Limits

What you need

• One or more nodes with Proxmox VE 7 or 8 (they are Debian based, so the Debian agent package fits).
• A place for the BackupZit console: a small Linux VM with 2 vCPU, 2–4 GB RAM and a 16–20 GB disk. The console stores no backup data itself, so it can run as a VM on the same cluster.
• Backup storage outside the Proxmox node — for example a Linux server or NAS reachable over SFTP, an SMB share, an S3-compatible bucket or a BackupZit hardened repository. The agents write to it directly.
• Network: the agents reach the console on TCP port 8443.

Step 1 — Install the console

The quickest way on Proxmox is the ready-made appliance image backupzit-appliance.qcow2 from the download page (Debian, PostgreSQL and the console, already set up):

1. Create a VM without a disk: 2 vCPU, 2–4 GB RAM, VirtIO network.
2. Copy backupzit-appliance.qcow2 to the node and import it as the VM's disk (replace <vmid>):

   qm importdisk <vmid> backupzit-appliance.qcow2 local-lvm

3. Attach the imported disk as SCSI, make it the boot disk and enable the QEMU guest agent in the VM options.
4. Start the VM. Its screen shows the address of the web console and the initial password of the user admin. Open https://<address>:8443, sign in and change the password.

On the VM's own screen you can sign in as bzadmin to set a static address, the server name and the time zone (the appliance starts in UTC, and schedules run in the console's time zone). Prefer an existing Debian, Ubuntu, AlmaLinux or Rocky Linux server? The one-line install script on the download page does the same there.

Step 2 — Add a storage target

In the console open Storage and add a target. Typical choices for Proxmox backups:

Leave Encrypt backups on (the default): everything is encrypted with AES-256-GCM on the node before it leaves it. The console then shows a recovery key — print the recovery sheet or put the key in a password manager, away from the backups. With the key, the storage location and its credentials you can restore even if the console is lost; without the key nobody can read the backups.

Step 3 — Install the agent on every node

1. In the console open Agents and click Create enrollment token. You get an enrollment code (BZ1-…) that is valid for 7 days and works for any number of machines.
2. Download the Linux agent — Debian / Ubuntu package from the Agents page to the node and run:

   apt install ./backupzit-agent_*.deb
   backupzit-agent enroll --code "BZ1-..."
   systemctl enable --now backupzit-agent

3. Within a minute the node appears on the Agents page with the badge Proxmox VE · N guests.

The agent uses the node's own tools (qm, pct, pvesm, LVM, ZFS, Ceph). No Proxmox API token or root password is stored in the console. In a cluster, install the agent on every node.

Step 4 — Create the backup job

1. Open Backup jobs, create a job and select the node's agent.
2. Choose Virtual machines (Proxmox VE, Hyper-V, VMware), then All VMs (and containers) on the host — guests created later are included automatically — or tick individual guests.
3. Pick the storage target from step 2.
4. Set a schedule, for example every working day at 22:00. Jobs can also repeat every 15 minutes to 12 hours, run once a month, or start after another job has finished.
5. Set the retention. Example: 3 most recent, 7 daily, 4 weekly, 6 monthly keeps about half a year of history with around 20 restore points.

What happens in each run:

1. A temporary Proxmox snapshot (backupzit_…) is taken; the guest keeps running.
2. Every disk is read from the snapshot in 1 MiB blocks. Empty blocks are not stored, and blocks that are already in the repository are not uploaded again — after the first backup, only changed data travels over the network. Each backup is still a complete restore point.
3. The snapshot is removed. The guest configuration (CPU, memory, network, disks) is stored with the backup.

Because unchanged data is stored only once, long retention costs little extra space.

Which disks can be backed up while the guest runs

Stopped guests can be backed up on all of these. Disks marked Backup: no (backup=0), passed-through physical disks and bind mounts are skipped and reported as warnings.

Step 5 — Make the backups application consistent

If the QEMU guest agent runs inside a VM and is enabled in its options, Proxmox freezes the VM's file systems for the snapshot, so databases and other applications are captured in a clean state. Without it the backup is crash consistent — like after a power loss.

In a Debian or Ubuntu VM:

apt install qemu-guest-agent
systemctl enable --now qemu-guest-agent

In Windows VMs install the VirtIO guest tools. Then enable the agent for the VM on the node (it takes effect after the next full stop and start of the VM):

qm set <vmid> --agent enabled=1

The run page of each backup shows, per guest, which disks were read and how the guest was captured.

Step 6 — Keep an off-site copy (3-2-1)

The 3-2-1 rule: three copies of your data, on two different media, one of them off-site. Add a second job of the kind Backup copy, select the Proxmox job as its source and an off-site target, such as an S3 bucket with Object Lock or a hardened repository in another building.

• The agent copies the existing backups; the VMs are not read again.
• Only data that is not yet at the destination is sent, encrypted with the destination's key.
• By default the copy runs after each backup of the source job; any schedule works, e.g. once a night for a slow line.
• The copy has its own retention, e.g. 7 daily on the NAS and 12 monthly in the cloud.

VMs can be restored from the copy like from the original — whole VMs, single files and instant recovery. More about immutable copies on the ransomware protection features.

Step 7 — Prove that the backups boot

Readable blocks do not prove that a VM still starts. Under Settings → Restore tests switch on Boot test for Proxmox VM backups. The restore test then starts every VM of the newest backup on the job's node, one after another, directly from the backup, with a new ID and its network cards disconnected so it cannot conflict with the original — and deletes it again afterwards.

• A VM passes when its QEMU guest agent answers in time, which means the operating system booted. VMs without the guest agent pass when they keep running for a minute and are shown as running rather than booted.
• The node needs free memory for one more VM while the test runs.
• In addition, a data check (monthly by default) reads every piece of stored data and verifies it against its checksum, to find damage on the storage itself before you need the backup.

Restoring

Open a backup run (from the job page or Activity) and choose Restore a VM or container.

Whole VM or container

• Restore on any node with the agent — also a node of another cluster.
• As a new guest with the next free ID (default) while the original keeps running; the copy gets new MAC addresses. Or with the original ID after the guest was deleted, optionally replacing an existing one.
• Choose the name and the storage for the disks, and whether to start the guest after the restore.
• Every restore gives VMs a new generation ID (vmgenid), so Windows domain controllers detect the rollback safely.

Instant recovery: the VM runs in seconds

A normal restore takes as long as copying the disks. With Instantly, running from the backup the agent serves the disks read-only from the backup and starts a new VM whose writes go to local overlays. When you are satisfied, Finish moves the disks to the chosen storage while the VM keeps running (qm disk move); Discard VM deletes the VM and its changes. The VM is as fast as the backup storage, so a repository on a local disk or a fast network share works best. Instant recovery is for VMs, not containers.

Single files

Click Browse files in the guest table of a backup run. The console reads the disk straight from the backup — nothing is restored first — and lets you browse NTFS, ext2/3/4 and XFS, also inside LVM. Download files (several as a ZIP) or restore them to a folder on any agent. Browsing in the console needs the backup on network storage (SFTP, S3, SMB, Azure or a hardened repository).

Replicas for the most important guests

Under Advanced in the job, Keep replicas of the VMs keeps a stopped copy of every guest up to date on another node or cluster after each backup. Only changed blocks are written — typically a few seconds per backup. If a guest is lost, Start replica runs it with the data of the last backup, without a restore.

From the command line

Everything also works without the console, for example to rebuild a node after a disaster:

backupzit-agent pve list
backupzit-agent pve show    --repo ... latest
backupzit-agent pve restore --repo ... --vmid 100 --new-vmid -1 --storage local-lvm --start latest

Limits to know

• Supported are Proxmox VE 7 and 8. XCP-ng is not supported.
• Container disks on ZFS subvolumes are not supported yet.
• Raw disks on directory, NFS or CIFS storage and disks on thick LVM can only be backed up while the guest is stopped.
• In a cluster, a job backs up the guests on its own node. A guest that was migrated to another node is reported as a warning — use All VMs (and containers) on the host on every node so migrated guests stay covered.
• Cloud-init drives are not stored; they are recreated from the configuration on restore.

Next steps

BackupZit is free and open source (AGPLv3), without limits on VMs or nodes. Download it, see all Proxmox features, or read the full chapter Proxmox VE virtual machines in the user guide in the console. Questions are welcome in GitHub Discussions; companies can get commercial support from MaxZit.