Introduction

Someone deletes a config file on a VM, a database export gets overwritten, or a user swears they "definitely didn't touch that spreadsheet" right before it goes missing. Your backups are fine — you've got a Proxmox Backup Server snapshot from last night — but the fix people reach for is restoring the entire VM to a new ID, booting it, and copying one file out by hand. That works, but it means spinning up a whole duplicate machine, waiting for a full restore of every disk, and cleaning up afterward, all to recover a few kilobytes of data.

Proxmox Backup Server doesn't require any of that. Every backup stored on PBS can be browsed and picked apart file by file, without touching the original VM or container and without a full restore ever happening. This guide covers exactly how that works: the File Restore browser in the Proxmox VE GUI, the proxmox-file-restore command line tool for scripting it, and the specific cases where file-level restore can't help and a full restore is still the right call.

This guide assumes Proxmox VE 8.x or 9.x with backups stored on Proxmox Backup Server 3.x or later — the workflow has been stable across that range.

What You Will Learn

  • How single file restore actually works under the hood, and why it only works for PBS-backed backups
  • How to browse a VM backup's disks and a container backup's filesystem from the Proxmox VE GUI
  • How to download individual files or whole directories without restoring anything
  • How to do the same thing from the command line with proxmox-file-restore, including encrypted backups
  • Which filesystems and disk layouts are and aren't supported
  • The errors you'll hit most often and how to work around them

What Is File Restore?

File Restore is a feature of Proxmox Backup Server, exposed through Proxmox VE's web interface, that lets you open a backup snapshot as a file browser instead of an all-or-nothing restore job. You navigate down into the backup's contents, tick the files or folders you actually want, and download them directly to your workstation as-is or as a zip.

The browsing experience differs depending on what got backed up:

  • Containers (LXC): a container backup is stored as one or more pxar archives (typically root.pxar for the root filesystem, plus one per mount point). The file tree shown is just that archive's contents — open it and you're looking at the container's filesystem exactly as it existed at backup time.
  • Virtual machines (QEMU): a VM backup has no built-in idea of files — it's raw block data. The first layer of the browser shows each backed-up drive (drive-scsi0.img.fidx, drive-virtio1.img.fidx, and so on). Opening one reveals the partition table, then each partition, and only then an actual file listing — because getting there requires PBS to parse a partition table and a filesystem it has never had special knowledge of before.

That last point is why VM-side file restore needs help it doesn't need for containers. To safely read an arbitrary partition and filesystem out of a disk image without running untrusted parsing code directly on your Proxmox VE host, the system spins up a small, temporary VM in the background — it isn't listed alongside your normal guests, and it shuts itself down automatically after a short idle timeout. That temporary VM mounts the backed-up disk image read-only, walks the filesystem, and reports back what it finds. You never interact with it directly; it exists purely as an isolation boundary between "parse a filesystem from a backup file that could theoretically be crafted maliciously" and "your hypervisor host."

Why Would You Use It?

The obvious alternative is a full restore: pick the backup, restore it to a new VM ID, boot it (for a VM) or just start it (for a container), and grab what you need. File Restore skips essentially all of that:

  • No duplicate VM. You don't need a spare VM ID, spare disk space for a full copy of every disk, or a running instance eating RAM and CPU while you dig around.
  • No waiting for a full restore. Restoring a 200GB VM disk to recover one 4KB config file is wasted I/O and time, especially against slower storage or over a WAN link to a remote PBS.
  • No boot required. A full restore of a VM only gets you the file once the VM actually boots (or you attach the disk elsewhere). File Restore reads the backup directly — there's no OS to boot, no drivers to worry about, no risk of the restored VM conflicting with the original on the network.
  • Safer for forensics. If you're trying to recover something because a VM got compromised or corrupted, spinning up a full copy of it is itself a small risk. Read-only file browsing doesn't execute anything from inside the guest.

It's not a replacement for full restore in every case — if you need the VM itself running again, or you need dozens of files scattered across the disk with directory structure and permissions perfectly intact for a running system, a full restore is still simpler. File Restore is for the "I just need this one thing back" case, which in practice is most restore requests.

Prerequisites

  • Proxmox VE 8.x or 9.x, with a Proxmox Backup Server datastore already added as storage (see our guide on setting up Proxmox Backup Server if you haven't done this yet)
  • At least one existing backup snapshot of the VM or container you want to recover a file from, stored on that PBS datastore — File Restore does not work on vzdump backups stored on local disk, NFS, or any non-PBS storage
  • A user account with at least VM.Backup and Datastore.AllocateSpace permissions on the relevant storage/VM (the same permissions you'd need to run a normal restore)
  • If the backup is encrypted client-side, the encryption key or passphrase used at backup time — File Restore cannot browse an encrypted backup without it
  • For the CLI method: shell access to a Proxmox VE node, and either an existing PBS storage entry in /etc/pve/storage.cfg or the datastore's connection details (host, datastore name, and an API token or user credentials)

Step-by-Step Tutorial

Step 1: Find the backup snapshot in the GUI

In the Proxmox VE web interface, click the PBS storage entry in the left-hand tree, then open its Backups content tab. Find the row for the VM or container you need — the list shows every retained snapshot with its timestamp. Pick the snapshot from just before whatever got deleted or broken; if you're not sure exactly when, start with the most recent one and work backward.

Step 2: Open File Restore

Select the snapshot row and click File Restore in the toolbar above the list. A new window opens showing the top level of that backup's contents. The first time you do this for a given snapshot there's a short pause — for a VM backup, this is the temporary helper VM starting up and mounting the disk image in the background. It's normal, and it's the same delay whether you're pulling one file or browsing around for ten minutes.

Step 3: Browse a container backup

For an LXC container, the top level lists one entry per pxar archive, almost always just root.pxar unless the container has extra mount points backed up separately. Open it and you're browsing the container's filesystem directly — /etc, /var, /home, all exactly as they were at backup time, with normal folder navigation.

Step 4: Browse a VM backup

For a QEMU VM, the top level lists each disk that was included in the backup. Open a disk to see part, representing its partition table, then open that to see the individual partitions (numbered, matching what you'd see from fdisk -l inside the guest). Open a partition to get an actual file listing, provided the partition's filesystem is one PBS knows how to read (ext4, XFS, and NTFS are all well supported; see the Common Errors section below for what isn't). From here it's normal folder browsing — navigate to wherever the file you need actually lives.

Step 5: Download what you need

Select one or more files or folders and click Download. A single file downloads as-is. Multiple files, or any folder, get zipped on the fly and downloaded as one archive — nothing is written back to Proxmox storage in the process, this all happens straight to your browser.

Step 6: Do the same thing from the CLI with proxmox-file-restore

Everything the GUI does is also available as a command you can script or run over SSH, using the proxmox-file-restore tool that ships on every Proxmox VE node. It takes a PBS group/snapshot identifier and a path inside that snapshot, mirroring the same layer structure as the GUI.

List what's available under a given path first:

proxmox-file-restore list vm/100/2026-07-14T02:15:00Z /drive-scsi0.img.fidx/part/2/etc/

Then extract a specific file, writing it out to a local path:

proxmox-file-restore extract vm/100/2026-07-14T02:15:00Z /drive-scsi0.img.fidx/part/2/etc/nginx/nginx.conf ./nginx.conf

For a container, the path starts with the archive name instead of a disk image:

proxmox-file-restore extract ct/105/2026-07-14T03:00:00Z /root.pxar/etc/nginx/nginx.conf ./nginx.conf

If you're targeting a PBS datastore that isn't already configured as Proxmox VE storage on that node, point the tool at it directly with a repository string, the same format proxmox-backup-client uses:

proxmox-file-restore extract --repository backup-user@pbs!token-name@10.0.0.20:main \
  vm/100/2026-07-14T02:15:00Z /drive-scsi0.img.fidx/part/2/etc/nginx/nginx.conf ./nginx.conf

You'll be prompted for the token secret, or you can set it ahead of time in the PBS_PASSWORD environment variable to run this unattended.

Step 7: Restoring from an encrypted backup

If the backup job used client-side encryption, both the GUI and the CLI need the encryption key before they can read anything past the top-level listing — without it, PBS can see that chunks exist but can't decrypt them into a filesystem to browse. In the GUI you'll be prompted to upload the key file when you open File Restore on an encrypted snapshot. On the CLI, pass it explicitly:

proxmox-file-restore extract --keyfile /root/.proxmox-backup-encryption-key.json \
  vm/100/2026-07-14T02:15:00Z /drive-scsi0.img.fidx/part/2/etc/nginx/nginx.conf ./nginx.conf

If you don't still have that key, there is no way around this — that's the entire point of client-side encryption, and it applies identically to a full restore.

Commands Explained

  • proxmox-file-restore list <snapshot> <path> — lists the contents of a path inside a backup snapshot without extracting anything, useful for confirming a file exists before pulling it
  • proxmox-file-restore extract <snapshot> <path> <target> — extracts a single file or, given a directory path, recursively extracts everything under it to <target>; pass - as the target to stream a single file to standard output instead of writing it to disk
  • --repository <user@pbs@host:datastore> — overrides which PBS instance and datastore to talk to, needed when the node running the command doesn't already have that datastore configured as local storage
  • --keyfile <path> — supplies the client-side encryption key for encrypted backups; without it, encrypted snapshots can be listed at the top level but not browsed into
  • vm/<vmid>/<timestamp> and ct/<vmid>/<timestamp> — the group/snapshot identifier format PBS uses internally; you can get the exact timestamp string from the Backups tab in the GUI, or by running proxmox-backup-client snapshot list <group> --repository ...

Common Errors

  • "File Restore" button is missing or greyed out. The backup isn't on Proxmox Backup Server storage. Check the storage type in Datacenter → Storage — vzdump backups on local disk, NFS, or CIFS storage don't support this feature at all, full stop.
  • Browsing a VM disk gets stuck at "part" with nothing underneath, or a partition opens to an empty listing. The filesystem on that partition isn't one PBS can parse. This is most common with LVM logical volumes, ZFS pools, or Btrfs used inside the guest (as opposed to on the Proxmox host), and with any filesystem sitting behind full-disk encryption at the guest level, like BitLocker or LUKS — PBS has no way to see past guest-level encryption regardless of whether the backup itself is encrypted.
  • The browser window hangs for a long time on first open, then times out. The temporary helper VM couldn't start — usually because KVM/nested virtualization isn't available on the node (common inside a nested Proxmox VE test lab), or the node is under enough memory pressure that it couldn't allocate RAM for the helper VM. Check /var/log/proxmox-backup/file-restore/ on the node for the specific failure from that run.
  • "decryption failed" or the top level lists fine but nothing opens. Wrong encryption key, or no key supplied at all for a backup that used one. Confirm the fingerprint of the key you're using matches what's shown against the backup job's configuration.
  • CLI extract works but the file looks truncated or corrupted. Usually a target path typo pointing at a partition boundary or a sparse region rather than the actual file — re-run list one level up to confirm the exact path before extracting.

Troubleshooting

Start with the log, every time: /var/log/proxmox-backup/file-restore/ on the Proxmox VE node holds a per-attempt log from the temporary helper VM, and it's almost always more specific than whatever the GUI shows. A failure to mount will say exactly which filesystem type it detected and why parsing failed, which tells you immediately whether you're dealing with an unsupported filesystem versus something else.

If the helper VM won't start at all, confirm KVM is actually available on the node with kvm-ok or by checking /dev/kvm exists — nested virtualization setups (Proxmox VE inside VMware or VirtualBox for testing) frequently don't expose this correctly, and File Restore for VM backups silently can't function without it. Container file restore has no such dependency, since it's just unpacking a pxar archive rather than mounting a disk image.

If a specific partition simply won't open and the guest is Linux, boot the backup as a real full restore once, check what filesystem and volume manager it actually used with lsblk -f and pvs/vgs, and you'll know for certain whether it's an LVM or ZFS layout that File Restore was never going to be able to parse — at that point, a full restore (or attaching the restored disk to a helper VM manually) is the only path forward, not a File Restore limitation you can work around.

For CLI runs against a remote PBS instance, connection failures are almost always the same handful of causes as with proxmox-backup-client: wrong fingerprint (add --fingerprint from the datastore's TLS fingerprint), wrong or expired API token, or the datastore name in the repository string not matching what's actually configured on the PBS side. Double-check against the exact repository string Proxmox VE itself uses for that storage in /etc/pve/storage.cfg.

Best Practices

  • Test file restore on a real backup before you need it under pressure. Pick any existing snapshot right now and pull a random file out with both the GUI and the CLI, so you know what a working run actually looks like and how long the helper VM takes to spin up on your hardware.
  • Don't treat it as a substitute for restore testing. Being able to read a config file out of a backup tells you nothing about whether the VM as a whole would actually boot from that same backup — keep doing full restore drills separately.
  • Prefer the CLI for anything you'll need to repeat. A one-off recovery is fine in the GUI, but if you're regularly pulling the same log directory or config path out of backups for auditing or comparison, script it with proxmox-file-restore instead.
  • Keep encryption keys backed up somewhere other than the PBS datastore itself. An encrypted backup with a lost key is unrecoverable by either full restore or File Restore — there's no bypass for either.
  • Restrict who can use File Restore in shared environments. It requires the same backup-read permissions as a full restore, so anyone who can restore a VM can also browse its filesystem file by file — factor that into your RBAC role design if VMs contain sensitive data.

Frequently Asked Questions

Does File Restore work on vzdump backups stored on local or NFS storage?

No. File Restore is a Proxmox Backup Server feature specifically — it relies on PBS's chunk-based storage format to address individual pieces of a backup without reading the whole archive. A vzdump backup on local disk or NFS is a single compressed archive file; there's no way to browse into it without decompressing and restoring it in full.

Do I need to stop or restore the original VM to use File Restore?

No. The original VM or container is completely untouched by this process — File Restore only ever reads from the backup snapshot on PBS. For VM backups, a separate temporary helper VM does the reading, and it has no connection to your original guest.

Can I restore a file directly back onto the running VM instead of downloading it to my computer?

Not automatically — File Restore only downloads to wherever you run the browser (your workstation) or wherever you point the CLI's target path. To get a file back onto the live VM, download it and then copy it in yourself over SSH, SCP, or whatever file transfer method that guest supports.

Why can I browse some partitions but not others on the same VM disk?

Each partition is parsed independently, so a mixed disk (say, an EFI system partition plus an LVM-managed root partition) can have some partitions browsable and others not, depending purely on what filesystem or volume manager sits on that specific partition.

Is File Restore available for Windows VMs?

Yes, as long as the disk uses a filesystem PBS can parse — NTFS is well supported, so a typical Windows VM's C: drive browses normally. What won't work is anything sitting behind BitLocker, since that's guest-level encryption PBS has no visibility into regardless of backup encryption settings.

Does using File Restore count against my PBS datastore's storage or change the backup in any way?

No. It's entirely read-only against the existing backup chunks — nothing is written to the datastore, and the snapshot you're browsing is unaffected and remains exactly as it was for future full restores.

Conclusion

Most restore requests aren't "bring the whole VM back," they're "get me that one file back," and treating every request as the former wastes time and storage I/O for no reason. File Restore turns any Proxmox Backup Server snapshot into a browsable filesystem you can pull individual files from in seconds, from the GUI for one-off recoveries or the CLI when you need to script it. It has real limits — no non-PBS storage, no guest-level LVM/ZFS/encrypted volumes, and it still needs KVM available for VM backups — but for the ordinary case of recovering something small without disturbing anything else, it's the tool to reach for before a full restore.