How to back up Proxmox VE virtual machines and containers

What vzdump backs up

Proxmox VE is open-source virtualization software (AGPL v3), built on Debian, for KVM virtual machines and LXC containers. Each vzdump backup is a full copy of one guest, configuration and disks, in one archive named by type, ID and time: vzdump-qemu-101-2026_10_04-02_30_01.vma.zst for a VM, vzdump-lxc-102-2026_10_04-02_31_12.tar.zst for a container.

• VM disks are included unless set to backup=0.
• Containers: the root disk, plus volume mount points whose Backup option is on, never bind or device mounts. /tmp/?*, /var/tmp/?* and /var/run/?*pid are skipped unless --stdexcludes 0.

Pick a backup mode

A guest that isn't running is always backed up in stop mode. A VM in snapshot mode is only crash-consistent unless the QEMU guest agent runs inside it, letting Proxmox flush and freeze its filesystems. Install it in the guest (Debian, Ubuntu):

sudo apt install qemu-guest-agent

Enable it on the host, stop and start the VM from Proxmox (a reboot inside the guest is not enough), and check it answers:

qm set 101 --agent enabled=1

qm guest cmd 101 ping

The task log then shows issuing guest-agent 'fs-freeze' command and issuing guest-agent 'fs-thaw' command. A freeze gives clean filesystems, not database dumps: PostgreSQL and MySQL recover from it as after a crash. Also dump them inside the guest (pg_dump, mysqldump).

Add a backup storage

Backups go to a storage with the backup content type. The built-in local (/var/lib/vz/dump) sits on the host's own disks; an NFS share on another machine is better:

pvesm add nfs backup-nfs --server 10.0.0.20 --export /srv/pve-backups --content backup --prune-backups keep-daily=7,keep-weekly=4,keep-monthly=6

It mounts at /mnt/pve/backup-nfs, with archives in dump/; pvesm add cifs works the same for SMB. The docs recommend a Proxmox Backup Server on its own host, with NFS as the alternative.

Back up from the command line

vzdump 101 --mode snapshot --storage backup-nfs --compress zstd

vzdump writes a temporary .dat file and renames it when complete, so a file with its final name is a finished backup.

Schedule backup jobs

Datacenter → Backup → Add in the web interface creates a job. Jobs live in /etc/pve/jobs.cfg, on the cluster filesystem, and the pvescheduler daemon runs them. From the shell:

pvesh create /cluster/backup --schedule "02:30" --storage backup-nfs --all 1 --mode snapshot --compress zstd --repeat-missed 1

Schedules are systemd-style calendar events: 02:30 daily, sat 03:00 on Saturdays. --repeat-missed 1 runs a job missed while the host was off; by default it is skipped. List jobs with pvesh get /cluster/backup; change them in the GUI or with pvesh set.

Retention with prune-backups

keep-last, keep-hourly, keep-daily, keep-weekly, keep-monthly and keep-yearly apply in that order, each only to backups older than those already kept. Set them on the storage, as above, or per job to override it. The default, keep-all=1, deletes nothing.

Worked example: daily backups with keep-daily=7,keep-weekly=4,keep-monthly=6 keep at most 17 per guest: 7 daily, then 4 weekly, then 6 monthly, reaching about 7 months back. At 20 GB per compressed backup, that is up to 340 GB for one VM on a file storage. Preview what a policy deletes:

pvesm prune-backups backup-nfs --vmid 101 --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --dry-run 1

A protected backup (--protected 1) is never pruned, but only Proxmox enforces that: anyone who can write to the storage can still delete the file.

Restore a VM or a container

qmrestore /mnt/pve/backup-nfs/dump/vzdump-qemu-101-2026_10_04-02_30_01.vma.zst 101 --storage local-lvm

pct restore 102 /mnt/pve/backup-nfs/dump/vzdump-lxc-102-2026_10_04-02_31_12.tar.zst --storage local-lvm

• --storage picks where disks go; by default, the original storage.
• A taken ID stops the restore; --force 1 overwrites that guest.
• From PBS, pass the volume ID from pvesm list pbs-main --vmid 101 instead of a path.
• --live-restore 1 (PBS only) starts the VM at once and copies data in the background; if it fails, the VM is left in an undefined state.
• A vzdump file restores on another Proxmox VE host the same way.

In the web interface, select the backup in the storage's backup list and click Restore. PBS backups also have File Restore, which browses an archive and downloads single files; from file-storage backups, restore to a spare ID and copy files out.

Proxmox Backup Server

Proxmox Backup Server (PBS) is a separate server, also free and open source (AGPL v3). Add its datastore as a storage and jobs target it like any other:

pvesm add pbs pbs-main --server 10.0.0.30 --datastore main --username backup@pbs --fingerprint <fingerprint> --encryption-key autogen --password

• Deduplication. VM disks are split into 4 MiB chunks, containers into variable ones, each stored once. VMs can use dirty bitmaps to send only changed chunks; every backup still restores in full.
• Verify jobs recheck chunks against their SHA-256 checksums. The docs advise a frequent job for new backups and a monthly full reverify.
• Garbage collection frees chunks that pruned backups no longer use; start with weekly.
• Encryption. --encryption-key autogen creates a client-side AES-256-GCM key at /etc/pve/priv/storage/pbs-main.enc. Without that key the backups can't be read, and a key kept only on the host dies with it.

Print a paper copy (text and QR code) for a safe, and keep one in a password manager:

proxmox-backup-client key paperkey /etc/pve/priv/storage/pbs-main.enc --output-format text > qrkey.txt

Get a copy off the host

Backups on local die with the host's disks; an NFS server in the same rack shares the building. The 3-2-1 rule wants a copy elsewhere. With PBS, run a second PBS at another site that pulls: on it, add the main server as a remote, then a sync job:

proxmox-backup-manager remote create pbs-main --host pbs-main.example.com --userid sync@pbs --password 'SECRET' --fingerprint <fingerprint>

proxmox-backup-manager sync-job create pull-main --remote pbs-main --remote-store main --store offsite --schedule '04:00'

Only new chunks cross the network, and pulling leaves the main site with no login that can delete the off-site copies. Leave remove-vanished off, or deletions on the main server follow; prune off-site with its own policy. --encrypted-only and --verified-only restrict what is synced. Current PBS releases can also keep a datastore in an S3-compatible bucket, with a local cache disk.

Without PBS, upload each archive as it finishes with a vzdump hook script and rclone (remote offsite, set up as that guide shows):

#!/bin/bash
# vzdump hook: copy each finished backup archive to the bucket.
# vzdump runs hooks with an almost empty environment, so set PATH here.
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

if [ "$1" = "backup-end" ] && [ -n "${TARGET:-}" ]; then
  rclone copyto "$TARGET" "offsite:my-bucket/pve-01/${TARGET##*/}" \
    --config /root/.config/rclone/rclone.conf || exit 1
fi
exit 0

• vzdump runs the script at every phase, phase name first; TARGET, the finished archive, is set only in backup-end. File storages only.
• A non-zero exit fails that guest's backup, so a failed upload reaches the job's notification.
• chmod 700 it, then add script: /usr/local/bin/vzdump-offsite to /etc/vzdump.conf (every backup on the node) or run pvesh set /cluster/backup/<job-id> --script /usr/local/bin/vzdump-offsite (one job).
• copyto never deletes: prune the bucket with a lifecycle rule or from cron, such as rclone delete offsite:my-bucket/pve-01 --min-age 60d --config /root/.config/rclone/rclone.conf.

Back up the host's own configuration

Guest backups don't include the host: storages, users, permissions, firewall, backup jobs, network. /etc/pve is pmxcfs, a FUSE view of the SQLite database /var/lib/pve-cluster/config.db, replicated to every cluster node. Archive both, plus the network and name files:

tar -czf /root/pve-host-$(hostname)-$(date +%F).tar.gz /etc/pve /var/lib/pve-cluster/config.db /etc/network/interfaces /etc/hosts /etc/hostname /etc/vzdump.conf

The docs' recovery: on a fresh host with nothing running, stop pve-cluster, put config.db in place (mode 0600), set /etc/hostname and /etc/hosts as on the lost host, reboot. The archive holds /etc/pve/priv (storage passwords, API token secrets, PBS keys), so encrypt it and keep it off the host.

Test a restore to a new VMID

Restore under a spare ID with a new MAC address, cut its network link so it can't take the original's IP, and start it:

qmrestore /mnt/pve/backup-nfs/dump/vzdump-qemu-101-2026_10_04-02_30_01.vma.zst 9101 --storage local-lvm --unique 1

qm set 9101 --net0 virtio,bridge=vmbr0,link_down=1

qm start 9101

On the console, check that services start and data is recent, note how long it took, then qm destroy 9101. Containers: pct restore 9102 <archive> --storage local-lvm --unique 1, pct set 9102 --net0 name=eth0,bridge=vmbr0,link_down=1, pct start 9102. See testing a backup restore.

Common errors and log lines

Frequently asked questions

Can Proxmox back up a VM while it is running?

Yes. Snapshot mode, the default, copies a running VM's disks without shutting it down. Install the QEMU guest agent so the guest's filesystems are frozen and clean in the backup.

Where does Proxmox store backups?

On the storage you choose. The local storage uses /var/lib/vz/dump; an NFS or CIFS storage uses the dump directory under /mnt/pve/<storage>.

Are Proxmox backups incremental?

On directory, NFS and CIFS storages every backup is a full archive. On Proxmox Backup Server only changed chunks are sent and stored, but each backup still restores as a full one.

Is Proxmox Backup Server free?

Yes. It is open source under the AGPL v3 with no limits on storage or clients. Paid subscriptions add the enterprise repository and support.