Restoring a single file from a VM backup (file restore)

Classic scenario: someone accidentally deleted an important file in a VM. You don’t want to roll back the whole VM — just that one file. PBS can open VM backups, make the filesystems inside readable and extract individual files. In PVE 8+ this works straight from the GUI.

Requirements

• Proxmox VE 7.2 or newer
• The VM’s filesystem is one of the supported ones (ext4, xfs, btrfs, NTFS, vfat — the important ones)

File restore via the PVE GUI

1. Open the backup overview in the PVE tree — either via the VM or via Storage → \<pbs-storage\> → Content.
2. Select the right snapshot (date/time).
3. Click File Restore (button at the bottom right).

A file browser opens:

• You see the backup’s disk images (e.g. drive-scsi0.img).
• Click the image → you see the partitions, then the directories inside, and finally the files.
• For each file or folder you can click Download — the file is downloaded locally.

For large folders, a ZIP is packed automatically and offered for download.

File restore via the CLI

If you’re working in the console or the GUI happens to be unavailable:

Important: VM backups are block images, not pxar archives — proxmox-backup-client mount doesn’t work for them. The way to go for VM disks is map: the image is exposed as a loop device, which you then mount yourself.

# Find the snapshot
proxmox-backup-client snapshot list --repository 12345@pbs@pbs01.xaweho.de:12345

# Expose the disk image as a loop device
proxmox-backup-client map \
  vm/100/2026-05-08T02:00:00Z \
  drive-scsi0.img \
  --repository 12345@pbs@pbs01.xaweho.de:12345

# The command prints the loop device, e.g. /dev/loop0.
# Partitions appear as /dev/loop0p1, /dev/loop0p2 and so on.
mkdir -p /tmp/restore-mount
mount -o ro /dev/loop0p1 /tmp/restore-mount/

# Copy the file
cp /tmp/restore-mount/etc/important.conf /tmp/recovered.conf

# Clean up
umount /tmp/restore-mount/
proxmox-backup-client unmap /dev/loop0

The mount is read-only (-o ro) — you can’t break anything.

File restore from an encrypted backup

If your backup was created with client-side encryption, you need the key:

proxmox-backup-client map \
  vm/100/2026-05-08T02:00:00Z \
  drive-scsi0.img \
  --repository 12345@pbs@pbs01.xaweho.de:12345 \
  --keyfile /etc/pve/priv/storage/xaweho-pbs.enc

Then as above: mount the loop device read-only, copy the file, umount and proxmox-backup-client unmap.

In the GUI, PBS detects this automatically and asks for the key path.

File restore from container backups

With LXC containers it’s easier: PBS backs up containers as a single TAR archive. You can extract it directly:

proxmox-backup-client restore \
  ct/200/2026-05-08T02:00:00Z \
  root.pxar \
  /tmp/container-restore/ \
  --repository 12345@pbs@pbs01.xaweho.de:12345

The directory /tmp/container-restore/ then contains the container’s complete root filesystem — you find the file and copy it back.

Best practices

• VM file restore is read-only. You can read from the backup, but not write — whatever you extract, you copy back into the running VM (via SSH, via drag-and-drop in the console, depending on your setup).
• For large files: download via the GUI is fine up to ~5 GB. For larger amounts of data, better use the CLI with map + mount + rsync back into the VM.
• For Windows VMs: NTFS is supported, but NTFS-specific permissions are not preserved. If you want to roll back a whole Windows installation — then do a VM restore after all.
• A mapped disk image stays open until you release it. Clean up after use: first umount, then proxmox-backup-client unmap — otherwise the loop device lingers.

Frequently asked questions

Which filesystems are supported? ext2/3/4, xfs, btrfs (read-only), vfat, NTFS (read-only). LVM volumes inside the VM are detected too. For encrypted volumes (LUKS, BitLocker) you need the VM-internal password — which PBS doesn’t have.

Can I download whole directories too? Yes. In the GUI, right-click a folder → “Download as ZIP”. For very large directories (~10 GB+) the browser runs out of memory — better use the CLI with rsync then.

Does this also work with a running VM? Yes. The backup snapshot is immutable — you work with the backup state at snapshot time, the running VM is unaffected.

Multiple files at once — how? In the GUI: select several files (Ctrl+click), then “Download as ZIP”. On the CLI: cp -r from the mount.

Can I do this from a PBS backup of a Windows server too? Yes. NTFS filesystems are readable and you see the directory structure. Permissions and ACLs are lost, though — when copying back into the running VM, put the file into a folder with the correct permissions.

What if the VM used ZFS or LVM-Thin? ZFS: the read-only mount works. LVM-Thin: PBS detects LVM volumes and shows them. In both cases you don’t need any VM-internal mount logic — PBS takes care of it.

What’s next

• Restoring a complete VM
• Understanding the backup overview in PBS