Proxmox Backup Server Restore: Full Recovery Guide

Proxmox Backup Server stores incremental, deduplicated snapshots of your VMs and containers. Getting data in is straightforward. Getting it out – under pressure, on unfamiliar hardware after a disk failure, or with HA in the mix – is where most operators find out whether their backup strategy actually works.

This guide covers five Proxmox Backup Server restore scenarios: full VM/CT restore, single-file recovery, bare-metal host rebuild, migration to different hardware, and datastore corruption recovery. Each has different prerequisites, different failure modes, and different definitions of “success.” PBS restores guest backups and backup data; rebuilding the PVE or PBS host configuration itself is a separate recovery task, covered in the bare-metal scenario below.

Before You Restore: What PBS Actually Needs

Before touching the first PBS restore dialog, confirm these four things are in place. Skipping this check is how operators waste 30 minutes on a restore that was never going to work.

PBS must be reachable from the PVE host. Not just pingable – the PVE node needs PBS added as a storage backend, with the correct IP, port (8007), datastore name, and credentials. Verify with pvesm status. If the PBS storage entry isn’t there or shows “error,” the restore dialog will be empty.

The certificate must be trusted, or the fingerprint must match. PBS uses TLS. When the server presents the default self-signed certificate, or another certificate the PVE host does not trust through its CA chain, the configured SHA-256 fingerprint must match. If PBS is rebuilt or its certificate is replaced, the pinned fingerprint changes and the PVE storage definition must be updated. With a certificate trusted by the PVE host, manual fingerprint pinning is not required. Connection will fail with an SSL error that looks like a network problem until you look at the actual log.

Encryption keys must be present. Determine how the backup was encrypted before searching for a key – there are three distinct cases. PVE-integrated encrypted PBS storage commonly stores the client-side key at /etc/pve/priv/storage/<STORAGE-ID>.enc (this lives in pmxcfs, so it’s cluster-wide, not tied to one physical node). Standalone proxmox-backup-client jobs commonly use ~/.config/proxmox-backup/encryption-key.json on whichever host ran the job. A configured master public key can also store an encrypted copy of the symmetric key with each backup, but recovering from that requires the separately-protected master private key – that’s a distinct workflow, not the same as the everyday client key. An encryption key isn’t required merely to define the PBS storage entry, but no key means no decryption – PBS will report a decryption failure. For bare-metal and cross-host PBS restores, this is the step operators forget. The Proxmox Backup Client encryption and master-key documentation covers key export and management in detail.

Target storage must have enough space. The restore will fail mid-way with “no space left on device” if the destination doesn’t have room. Check the logical size of every VM or CT volume in the backup – shown in the restore dialog or backup configuration – and compare it against the destination backend’s allocation model and available capacity with pvesm status. Don’t use the compressed or deduplicated PBS snapshot size as the restore-space requirement; thin-provisioned targets also need enough real free space and metadata capacity for the data written during restore and subsequent guest growth. If you’re unsure which backend the destination actually uses, Proxmox Storage: ZFS vs LVM-thin vs Ceph covers how each type reports and allocates space differently.

The common misconception: “backup exists = restore works.” A backup that hasn’t been verified, on a PBS instance with an expired or untrusted certificate, or a stale/mismatched pinned fingerprint, with no encryption key on the new host, is not a working backup. It’s data you can’t access.

Test Restore vs Production Restore

Before running any Proxmox Backup Server restore, decide which mode you’re in. The commands overlap, but the intent and precautions don’t.

Test restore – use when you want to validate the backup without affecting anything running:

• Assign a new VM ID (e.g. 9100 instead of 100)
• Always use --unique 1 to get new virtual NIC MAC addresses – it doesn’t regenerate the guest OS identity, machine ID, or SSH host keys, so check those separately if you’re running the test alongside the original
• Place the VM on an isolated bridge, not your production network
• Delete the test VM after confirming it works

Production restore – use when the original VM is genuinely gone and needs to be replaced:

• Prefer a free VMID or a deliberately removed failed-VM config over reusing the old ID. Only use --force 1 once you’ve confirmed the original VM definition should genuinely be overwritten and can’t start anywhere else – never against a VM that’s still active just to test a backup.
• Plan downtime explicitly – note other services depending on this VM before you start
• Still boot on isolated network first, then reconnect

Never restore over a running VM to test whether the backup is good. If something goes wrong, you’ve lost the running VM and may not have a clean restore either. An isolated test restore is far lower risk than overwriting a production guest, but it still consumes storage, I/O, network capacity, and operator time. Overwriting a live VM is not reversible.

Scenario	Downtime	Risk	Skill
File restore	Low	Low	Low
Full VM restore	Medium	Medium	Medium
Different hardware	Medium	Medium	Medium
Bare-metal recovery	High	High	High
Datastore corruption	High	Very high	High

Scenario 1 – Full VM or Container Restore

When it applies: The VM is gone, corrupted, or you need to roll back to a known-good state. This is a common Proxmox Backup Server restore operation and the one PBS is built around.

Add PBS as storage if not already present. In PVE GUI: Datacenter → Storage → Add → Proxmox Backup Server. Fill in server address, datastore name, credentials, and fingerprint. Or via CLI:

Port 8007 is the default and doesn’t need to be added to --server – use a separate --port <port> flag only if PBS listens elsewhere. Leaving --password without a value prompts interactively rather than putting the token secret in shell history.

Once added, navigate to Datacenter → Storage → [PBS storage] → Backups. Find the VM ID, select the snapshot, and click Restore. Full VM/CT restore documentation is available in the Proxmox VE Integration guide.

In the Restore dialog: set a target VM ID (new ID for parallel testing, same ID for direct replacement), set target storage, and check Unique to assign new virtual NIC MAC addresses – required if the original VM is still running anywhere on the network. This doesn’t touch the guest OS identity, machine ID, or SSH host keys – for a parallel test restore, plan to check the guest’s static IP, hostname, machine ID, any application cluster identity, scheduled jobs, and license bindings separately.

CLI equivalent for a full VM PBS restore – find the exact backup volume ID first rather than guessing the path format, since it can vary by PVE version and namespace:

Then restore using the exact returned volume ID:

For LXC containers, use the same discovery step, then pct restore with the returned volume ID:

Container restores require a separate check for bind and device mounts. Proxmox can restore the CT configuration entry, but the contents of host-path bind mounts and device mounts are never included in the guest backup. The restored CT may therefore start with the expected mount definition while the external source is missing, unmounted, empty, or owned by the wrong IDs. The LXC bind mounts guide covers which mount types actually get backed up and how to verify one after a restore.

Verify the exact option order and available flags against the installed version before relying on a copied example – qmrestore help and pct restore --help confirm what your specific PVE release actually accepts. Don’t enable “Start after restore” automatically – boot the VM manually after confirming the task completed without errors.

Logs: Start with the full task log in the PVE GUI, or copy the UPID and query it directly:

Raw files under /var/log/pve/tasks/ exist but are an implementation detail – use the task tools above first. For daemon-level errors, check the journals on both sides: journalctl -u pvedaemon and journalctl -u pveproxy on the PVE node, journalctl -u proxmox-backup and journalctl -u proxmox-backup-proxy on the PBS host. Don’t dismiss syslog either – storage, network, TLS, kernel, and filesystem failures can show up there before they reach the task log.

Verification: After the Proxmox Backup Server restore completes, don’t immediately expose the VM to the production network. Start it on an isolated bridge or with the NIC detached. Confirm the OS boots, check that critical services start, verify that data timestamps match the expected backup window. Then reconnect.

Scenario 2 – Single-File Recovery

When it applies: A config file was deleted, a directory was accidentally overwritten, or a user needs last week’s version of a specific document. A full PBS restore of the entire VM would be excessive and slow.

GUI file browser: In current Proxmox VE, select the PBS storage → Backups → click a backup snapshot → File Restore. A browser-based file tree opens. Navigate to the file, click Download. The file saves to your workstation – you then copy it into the VM via SCP or SFTP. No CLI required, works from any browser. Limitation: large files can be slow through the browser.

CLI via proxmox-file-restore: Snapshot and internal-path syntax is version- and archive-specific, so pull the exact snapshot ID and path from the tool rather than copying an example verbatim. List the snapshot contents first:

Then extract the specific file to standard output using a real shell redirect (not the arrow shown in some copy-pasted examples floating around). The third positional argument controls the destination – use - to send a single file to stdout and redirect it into a local file. For directories, stdout produces an archive rather than an extracted directory tree, so choose an explicit target directory or archive format instead:

Verification: Compare the recovered file against expected content. If it’s a config file, run a syntax check before placing it (nginx -t, sshd -t, etc.). Confirm the modification timestamp matches the expected backup window.

Scenario 3 – Bare-Metal Host Recovery

When it applies: The PVE host itself is gone – hardware failure, OS corruption, or total disk loss. You’re starting from scratch and need a full Proxmox Backup Server restore of all VMs and containers that lived on it.

PBS restores guest backups – it does not restore the Proxmox host operating system, cluster state, repository configuration, network setup, certificates, storage definitions, backup job schedules, HA resources, or node identity. Rebuilding the failed host is a separate reconstruction process that has to happen before any PBS restore of guests can even start. Treat these as two projects, not one, and this checklist as the first one:

• PVE version and enabled repositories
• /etc/network/interfaces (or the equivalent bridge/VLAN config)
• Hostname and DNS records
• Storage IDs and their backend types
• PBS storage definition and fingerprint
• Encryption key (see the field note below)
• Bridge and VLAN naming used by existing VM configs
• PCI passthrough configuration, if any
• HA and resource mapping definitions
• Firewall rules
• Backup job schedules
• Monitoring/alerting configuration
• Certificates
• Any non-default package inventory

This is the highest-stress recovery scenario, and the difference between a smooth rebuild and a long slog is usually whether someone documented the list above before the failure – not raw restore speed.

1. Install a fresh Proxmox VE. Install the same supported Proxmox VE release family or a newer supported release that understands the backed-up guest configuration – avoid restoring backups created with newer VM/CT configuration features onto an older PVE release. When rebuilding during an incident, minimizing unnecessary version changes reduces variables, but the backup format itself doesn’t require an identical major release. If you’re not sure what version path fits your environment, the Proxmox update guide covers version and upgrade path considerations. Run through the standard post-install checklist before adding PBS storage, not after.
2. Configure basic networking. The new host needs a static IP and a route to the PBS server before anything else works.
3. Add PBS as storage. Same process as Scenario 1 – server address, datastore, credentials, certificate trust or fingerprint, and namespace. An encryption key isn’t required merely to define the storage entry, but it’s a hard requirement for restoring client-side encrypted backups.
4. Restore guests one at a time. Find the exact backup volume ID with pvesm list <PBS-STORAGE-ID> --content backup, then use qmrestore with original VM IDs to preserve numbering, or new IDs if testing first. Reaching for --force to overwrite an existing config with the same ID should be a deliberate decision, not a default step – confirm the original definition genuinely needs replacing first.
5. Review network configs inside each VM. If the new host uses different bridge names, VMs may come up with no network access even though everything else looks correct.

Cluster membership needs a decision, not just a restore. If the failed host was part of a Proxmox cluster, decide explicitly whether the failed node will be replaced under the same identity, removed, or rebuilt fresh – and follow the documented cluster node replacement or removal workflow for whichever you choose. Restoring a stale /etc/pve or corosync.conf onto a live cluster, or bringing back a node with an identity that conflicts with what pmxcfs already has, can cause more damage than the original failure. Don’t create VMIDs that already exist elsewhere in the cluster’s configuration. Keep a copy of /etc/pve/corosync.conf and the quorum article’s recovery steps accessible before you need them.

Logs: Monitor journalctl -f on the new PVE host during PBS storage addition. Authentication failures, SSL errors, and connectivity issues may appear there before they show up as GUI errors.

Expected downtime: Depends on host rebuild time, network throughput between PVE and PBS, datastore performance, total guest disk size, and whether live restore is used – not a fixed number. Measure your first real bare-metal recovery end-to-end and use that measured time, not an estimate, as your actual RTO baseline.

Scenario 4 – Restore to Different Hardware

When it applies: Planned hardware migration, hardware upgrade, or relocating VMs to a different physical host. Unlike Scenario 3, this Proxmox Backup Server restore is usually scheduled maintenance – no panic involved.

The mechanics are identical to a full VM restore. The differences are in what breaks afterward.

NIC bridge mismatch is a frequent post-restore problem. If the source host had vmbr0 attached to enp3s0 and the destination has vmbr0 attached to eno1, VMs usually come up fine. But if the destination uses different bridge naming or has fewer bridges, VMs will restore successfully and then have no network access. Fix this in PVE’s VM hardware settings before booting, not after – see Proxmox Networking: Bridges, VLANs, Bonds if the destination’s bridge layout isn’t already documented somewhere.

CPU architecture changes require attention. A VM configured with cpu: host exposes the destination host’s CPU feature set after restore. The VM may still boot, but moving between Intel and AMD or between different CPU generations can change visible flags and affect nested virtualization, clustered applications, licensed software, or workloads that require specific CPU features. Use a compatible generic CPU model when cross-host portability is a design requirement – chosen for the oldest destination CPU and the workload’s actual requirements, not a single universal model – and verify required flags before production cutover.

Storage layout differences. If the source used ZFS and the destination uses LVM-thin, the PBS restore targets the destination’s storage type automatically. But if the source had multiple disks attached to different storage pools, ensure equivalent storage exists on the destination before starting restores.

Use --unique 1 for parallel testing. If the source VMs are still running while you set up the destination, always use --unique 1 when restoring. Without it, the virtual NIC MAC address is preserved from the backup – and if both VMs come up on the same network, you’ll have duplicate MACs causing intermittent failures that look like VM bugs. It won’t touch the guest’s own identity (hostname, machine ID) – check that separately if both copies might run at once.

Verification is the same as Scenario 1. Boot on isolated network, confirm services, verify data, then reconnect.

Scenario 5 – PBS Datastore Corruption

When it applies: Backup data on the PBS server itself is corrupted – disk failure on PBS, filesystem errors, silent bitrot, or the PBS host was lost and you need to rebuild access to its storage before any restore is possible.

This is the scenario where not having an offsite copy stops being theoretical.

Detection before disaster: PBS verification jobs run integrity checks on stored chunks and will catch corrupted snapshots before you try to restore them under pressure – schedule verification at an interval that matches your backup frequency, retention window, datastore size, and recovery objectives, rather than assuming one fixed schedule fits every environment. Without verification jobs enabled, corruption often surfaces only when a PBS restore fails – the worst possible moment. Enable verify jobs under Datastore → [datastore name] → Verify Jobs → Add. The Proxmox Backup Server maintenance documentation covers verification job configuration in detail.

If the PBS host is gone but disks are intact, treat this as a careful recovery, not a quick re-mount. Rushing the import/recreate steps below is how operators turn a recoverable datastore into a genuinely damaged one:

1. Preserve the disks read-only where the hardware and tooling allow it.
2. Inspect hardware and filesystem/ZFS health before importing anything.
3. Import or mount without forcing unless you understand why forcing is necessary:
   zpool import zpool import -o readonly=on <POOL> zpool status -v <POOL>
   Only use zpool import -f once you’ve confirmed the pool is safe to import and the previous host can no longer access it – importing a pool that’s still live elsewhere is how datastores get corrupted, not recovered. A forced import should be a deliberate response to a confirmed stale host ownership condition, not a routine command.
4. Verify the datastore root and .chunks layout look intact before pointing PBS at it.
5. Restore PBS’s own configuration from a separate config backup if one exists, rather than hand-writing a new datastore.cfg from memory. All PBS configuration files reside under /etc/proxmox-backup/ – back up that directory separately from the datastore.
6. If no config backup exists, reuse the existing datastore path with the supported current command rather than recreating it from memory:
   proxmox-backup-manager datastore create <STORE> <PATH> \ --reuse-datastore true
   Then verify the configuration: proxmox-backup-manager datastore show <STORE>.
7. Verify ownership and permissions on the datastore path match what PBS expects.
8. Run datastore inspection and verification before trusting any of it.
9. Test one file restore and one full guest restore before considering the datastore “recovered.”
10. Rebuild PBS-side configuration separately – reusing an intact datastore preserves the namespace directory structure and backup content, and backup groups and their recorded owners should be visible as expected, but users, ACLs, remotes, sync jobs, prune jobs, verify jobs, and notification settings live under /etc/proxmox-backup/ and need to be restored or rebuilt on their own.

Recreating datastore.cfg and restarting services is not itself a validation step – it makes PBS recognize the path, it does not confirm chunk integrity. Confirm the exact service unit names for your installed PBS version before restarting anything:

If the backup data itself is corrupted rather than just inaccessible, run a complete verification pass after reattaching the datastore:

Use --ignore-verified false when the purpose is to re-read snapshots rather than trust previous verification state. The GUI’s Verify All action under the datastore is the simpler path if you’d rather not use the CLI. Confirm the exact current syntax against your installed version before scripting anything – published examples can drift from the current release.

Verification identifies affected snapshots and chunks, but because of deduplication, damage to one shared chunk can affect multiple snapshots at once. Don’t assume deleting the one reported snapshot removes or isolates the underlying damage – preserve evidence, identify every impacted restore point from the verify output, and confirm an intact restore from another snapshot or replica before pruning anything. If corruption is widespread, you need the offsite copy.

Logs: On PBS: dmesg and the system journal for disk I/O errors. zpool status -v for ZFS-backed datastores. journalctl -u proxmox-backup captures service-level errors including chunk read failures.

Without an offsite copy: Partial recovery is possible if corruption is isolated to specific snapshots – identify intact ones from the verify output and restore from those. If a running PBS instance genuinely can’t be brought back but the indexes, chunks, and any required encryption key remain intact, a last-resort extraction path exists:

Treat this as an advanced, last-resort tool for pulling out specific data when reattaching the datastore normally isn’t possible yet – not a substitute for the reattach-and-verify procedure above, and not a primary recovery plan. If the datastore is physically gone with no secondary and no salvageable indexes/chunks, there’s no PBS restore path. For irreplaceable or production data, an independent off-site copy – three copies, two media types, one offsite – should be treated as a requirement, not an optional refinement.

Proxmox Backup Server Live Restore

Current Proxmox supports live restore for VM backups on PBS: the VM can start before the full disk restore completes, with reads served from the backup while the remaining blocks copy in the background. It’s a tool for reducing downtime during a Proxmox Backup Server restore, not a substitute for validating the guest afterward – a VM that boots early under live restore still needs the same post-restore checks as any other restore path. Performance during the live-restore window depends on PBS throughput, target storage, and network, and can be noticeably slower than after the background copy finishes. Not every workload should be exposed to production traffic the moment it boots under live restore – for anything latency-sensitive, let the background copy finish first. Use --live-restore 1 only where the storage and PVE version actually support it; check current documentation before relying on it for a bare-metal recovery under pressure.

Restore a PBS Backup to a New VMID

The safest default for any Proxmox Backup Server restore you haven’t validated yet: restore to a free VMID instead of the original one.

• Pick a VMID that isn’t in use anywhere in the cluster – not just on the current node
• Use --unique 1 for new virtual NIC MACs if the original VM might still be reachable on the network
• Boot on an isolated bridge first, not the production network
• Check application identity separately – hostname, machine ID, licensing, scheduled jobs, and any monitoring/HA/backup jobs that reference the old VMID won’t follow automatically
• Delete the test VM only after you’ve actually confirmed the restore is good, not right after it boots

Fix “VMID Already Exists” During PBS Restore

This error during a Proxmox Backup Server restore is a conflict to resolve, not a wall – work through it in order rather than reaching for --force as the first move:

1. Confirm whether the VM actually still exists in the cluster’s configuration, not just on the node you’re restoring to.
2. Confirm it isn’t running on another node in the cluster right now.
3. If you’re testing the backup, pick a new VMID instead of resolving the conflict.
4. Only remove the stale config after you’ve verified it’s genuinely stale, not just currently stopped.
5. Use --force only once you’ve deliberately decided to overwrite that specific VM definition.

Fix “Target Storage Does Not Exist” During Restore

This usually isn’t a broken Proxmox Backup Server restore – it’s a mismatch between what the backup expects and what the destination actually has configured. The original guest-disk storage ID doesn’t have to exist on the destination node; if it’s missing, choose another target in the Restore dialog or pass --storage <TARGET-STORAGE> explicitly. Check, in order: is the storage you’re selecting actually enabled on this specific node (shared storage can be node-restricted); does it support the right content type for VM disks; does it have sufficient capacity; does the PVE user running the restore have sufficient privilege on that storage; and does the disk mapping in the VM config point somewhere that makes sense on the new host. If the restored VM boots but immediately fails, the broader VM won’t start diagnostic workflow covers failure modes beyond storage mismatches.

PBS Restore Fails Because of Owner or Namespace Permissions

PBS separates backup group ownership, namespaces, and token privileges from PVE’s own permission model, as covered in the Proxmox Backup user management documentation – a Proxmox Backup Server restore failure here is rarely fixed by granting broader access on either side. Check backup group ownership and the namespace the backup actually lives in before assuming a permissions problem is a bug. If a token or user genuinely needs different ownership, PBS supports a change-owner operation for that specific case – appropriate when responsibility for future backups moves to another user or token, not as the default way to grant restore access. For restore-only access, assign a read-capable role on the correct datastore or namespace instead: DatastoreBackup covers backup and restore of owned groups, DatastoreReader covers inspecting and restoring datastore content, and Datastore.Read covers reading arbitrary backup content independently of the owner. Use whichever fits rather than granting global admin as the first troubleshooting step, which fixes the symptom while leaving the actual privilege-separation problem in place for next time.

Post-Restore Verification Checklist

Run this after every Proxmox Backup Server restore, regardless of which scenario you just completed:

Frequently Asked Questions

What happens if I lose the PBS encryption key?

Encrypted backups without the key are unrecoverable. No bypass, no recovery path, no support ticket that changes this – a Proxmox Backup Server restore simply can’t decrypt data it doesn’t have the key for. PBS uses AES-256 encryption with keys that only exist where you put them. Export keys and store them separately – not on the same host as PVE, not only on PBS. This is the one prerequisite that can’t be fixed after the fact.

Can I run a Proxmox Backup Server restore without the GUI?

Yes. qmrestore, pct restore, and proxmox-file-restore can all be used without the GUI. This matters for bare-metal recovery where you’ve just reinstalled PVE and haven’t set up a browser session yet. When restoring through a PBS storage already configured in PVE, the connection settings and credentials come from that storage definition rather than being supplied per command. Direct client usage outside a configured PVE storage may require repository, authentication, certificate trust or fingerprint, namespace, and encryption-key options.

How do I know if a PBS backup is corrupted before I need it?

Enable PBS verification jobs on a schedule matched to your backup frequency, retention window, and datastore size – weekly is a common starting point, but the right interval depends on your environment. A verify job reads and validates each chunk against its stored checksum. If a chunk fails, the job reports which snapshots are affected. Without this, the first indication of corruption is usually a failed restore – the worst possible moment to find out. Set it up under Datastore → Verify Jobs → Add.

How long does a Proxmox Backup Server restore typically take?

It depends more on storage speed and PBS load than on the network link alone – compression ratio, PBS disk throughput, VM disk layout, and whether live restore is used all move the actual number more than the raw link speed does. Measure a representative PBS restore end-to-end and record both throughput and complete service recovery time – that’s the only number that reflects your actual environment, not a generic estimate.

Can I restore a PBS backup to a different node than the original?

Yes – a Proxmox Backup Server restore doesn’t require the destination to be the same node the backup came from, as long as that node has PBS added as storage with the right credentials and certificate trust or fingerprint. The destination node needs access to a valid target storage that supports VM or CT volumes, but the original guest-disk storage ID doesn’t have to exist on the destination – explicitly select or pass a different target storage instead. Bridge names, hardware mappings, PCI passthrough, CPU features, and node-specific resources still require review. See Scenario 4 above for the full list of what breaks when the destination differs from the source.

What’s the difference between –unique and –force in qmrestore?

--unique 1 generates new virtual NIC MAC addresses during restore – it does not automatically regenerate the guest OS identity, machine ID, SSH host keys, application IDs, or every other hardware identifier. Use it when the original VM may still exist on the network, or when running a test restore alongside the original. --force 1 overwrites an existing VM config with the same ID without prompting – this should not be a routine production move. Prefer restoring to a free VMID, or deliberately removing the failed VM’s config after preserving evidence, and only reach for --force once you’ve confirmed overwriting that specific VM definition is intentional and the original can’t start anywhere else. Using --force without --unique on a VM that still exists elsewhere creates duplicate MACs and intermittent failures that are annoying to debug. Using neither on an existing VM ID will simply error out.