PBS File-Level Restore: Recover Single Files

Most restores are small: a deleted config file, a directory that a bad deploy overwrote, or a database dump from last Tuesday. A full VM restore is too slow for this, it needs disk space, and it can overwrite good data. Proxmox Backup Server (PBS) restores only the files you need from VM, container, and host backups. You can use the File Restore button in Proxmox VE, the proxmox-file-restore tool, or the catalog shell, and a monthly file restore test covers the 0 in a 3-2-1-1-0 backup strategy.

When a File Restore Is the Right Tool

Use a file-level restore when you need data, not a machine. Typical cases:

• A deleted or changed file in /etc, a web root, or a home directory.
• An old version of an application config before an update.
• A log file from a time before log rotation removed it.
• A database dump that a backup job wrote to disk.

Use a full restore when the guest itself is broken, when you migrate to new hardware, or when you need many directories at the same point in time. For the full restore steps, see the disaster recovery guide.

A file restore reads only the chunks that it needs: the file system metadata and the selected data. The rest of the backup stays on the datastore. With an offsite datastore, this means that a restore of one config file does not download the full VM disk.

Method 1: File Restore in the Proxmox VE GUI

This is the fastest method for VM and container backups. It is only available for backups on a Proxmox Backup Server storage.

1. In the Proxmox VE web interface, select your PBS storage in the resource tree.
2. Open the Backups tab.
3. Select the snapshot that you want to restore from.
4. Click File Restore.

A file browser opens. What you see depends on the guest type:

• Containers: The first level shows the pxar archives of the backup. Open an archive to browse the file system.
• VMs: The first level shows the drive images (for example drive-scsi0.img.fidx). Open a drive to see the storage technologies that PBS found on it. In the most basic case, there is an entry called part for the partition table, with one entry for each partition.

Select a file or a directory and click Download. Proxmox VE compresses a directory into a zip archive on the fly.

Not all VM data is always accessible. Some guest file systems and storage technologies are not supported. Test this for your own guests before you need it.

Encrypted backups

If your PBS storage uses client-side encryption, Proxmox VE keeps the key for that storage on the cluster (in /etc/pve/priv/storage/<storage-id>.enc). The File Restore browser uses this key, so the workflow is the same. If you rebuild a node, you must restore this key first. Without the key, nobody can read the backup. This includes your backup provider. For key handling, see PBS client-side encryption.

Method 2: proxmox-file-restore on the Command Line

The GUI uses the tool proxmox-file-restore in the background. You can call it directly, for example over SSH or in a script. If the command is missing, install the package proxmox-backup-file-restore.

First, set the repository. The format is user@realm!token@server:datastore. Take the server, the datastore, and the credentials from your connection details.

export PBS_REPOSITORY='backup@pbs!restore@pbs.example.com:mydata'
export PBS_PASSWORD='<api-token-secret>'

Then go down the tree one level at a time. Start at / to see the archives in the snapshot:

# Top level: the drive images
proxmox-file-restore list vm/100/2026-11-01T02:00:00Z /

# One level down: partitions and volumes on the first drive
proxmox-file-restore list vm/100/2026-11-01T02:00:00Z /drive-scsi0.img.fidx

# Browse into a partition
proxmox-file-restore list vm/100/2026-11-01T02:00:00Z /drive-scsi0.img.fidx/part/1/etc

Use the names from the output of each step. They depend on the disk layout of your guest.

When you find the file or directory, extract it:

# One file
proxmox-file-restore extract vm/100/2026-11-01T02:00:00Z \
  /drive-scsi0.img.fidx/part/1/etc/nginx/nginx.conf /root/restore/

# A directory as a zip archive
proxmox-file-restore extract vm/100/2026-11-01T02:00:00Z \
  /drive-scsi0.img.fidx/part/1/etc/nginx /root/restore/nginx.zip --format zip

Useful options:

• --format plain|pxar|zip|tar sets the output format.
• --zstd true compresses the output with zstd.
• --keyfile /path/to/key gives the encryption key for encrypted backups.

The temporary VM stops itself after a timer. To see the running restore VMs, use proxmox-file-restore status. To stop one at once, use proxmox-file-restore stop <name>.

Method 3: Catalog Shell for Container and Host Backups

Container backups and host backups made with proxmox-backup-client use the pxar archive format. For these archives, PBS keeps a catalog of all files. The catalog shell lets you search this catalog and restore only the files that match.

First, find the archive name in the snapshot:

proxmox-backup-client snapshot list
proxmox-backup-client snapshot files host/myserver/2026-11-01T02:00:00Z

Then open the shell on that archive:

proxmox-backup-client catalog shell host/myserver/2026-11-01T02:00:00Z root.pxar

pxar:/ > find etc/**/*.conf --select
pxar:/ > list-selected
pxar:/ > restore-selected /root/restore

restore-selected writes all selected files to the target path on the local host. The shell also has a restore command. It restores the full archive, or only the files that match a pattern:

pxar:/ > restore /root/restore --pattern etc/**/*.conf

For container backups, use the snapshot path of the container, for example ct/101/2026-11-01T02:00:00Z.

Mount an archive

If you prefer normal tools such as ls, diff, and cp, mount the archive as a read-only file system:

mkdir -p /mnt/pbs-restore
proxmox-backup-client mount host/myserver/2026-11-01T02:00:00Z root.pxar /mnt/pbs-restore

# Compare the backup with the live file
diff /mnt/pbs-restore/etc/nginx/nginx.conf /etc/nginx/nginx.conf

umount /mnt/pbs-restore

For encrypted backups, the client uses the default key location if you do not give --keyfile. For the full client setup, see how to back up any Linux server to PBS. Windows hosts are in the Windows client guide.

Which Method to Use

• File Restore (GUI): VM and container backups. Best for a quick restore of a few files.
• proxmox-file-restore: VM and container backups. Best for scripts and SSH sessions.
• Catalog shell: container and host backups (pxar). Best for a search by pattern in a large archive.
• FUSE mount: container and host backups (pxar). Best when you compare old and new files with normal tools.

File Restores and the 3-2-1-1-0 Strategy

The 3-2-1-1-0 strategy asks for three copies, two media types, one offsite copy, one immutable or air-gapped copy, and zero errors. The last digit is the hard one. A backup job that says "OK" only proves that data was written. It does not prove that you can read it back.

A file restore is the cheapest way to check this. It takes a few minutes, it needs almost no disk space, and it reads real data from the datastore. Do it on a schedule:

1. Each month, pick two or three guests at random.
2. Restore one known file from each guest, from the offsite copy.
3. Compare the file with the source, or check that it opens.
4. Write down the date, the snapshot, the result, and the time it took.

Run verify jobs in addition. A verify job checks the chunk hashes on the datastore. A file restore checks that the backup contains the data that you expect. You need both. For a full test plan, see restore testing and DR drills.

Wrapping Up

You do not need a full VM restore to get one file back. Use the File Restore button in Proxmox VE for quick work, proxmox-file-restore for scripts, and the catalog shell or a FUSE mount for container and host archives. Test one file restore each month from your offsite copy. Then the 0 in 3-2-1-1-0 is a fact, not a hope.

Frequently Asked Questions