restic mount
restic mount is one of Restic's most powerful features. It creates a virtual, read-only filesystem where every snapshot ever taken is visible as a normal folder. You can use standard tools like ls, cp, find, or even a GUI file manager to explore your backups and recover individual files.
mount turns your repository into a "Time Machine" drive. Instead of guessing which backup has your file, you can just cd into the snapshots and look for it manually.
Basic Syntax
restic mount [mountpoint] [flags]
Usage Steps
# 1. Create a directory for the mount
mkdir /mnt/restic
# 2. Mount the repository
restic mount /mnt/restic
# 3. Browse (in a separate terminal)
ls /mnt/restic/snapshots
Directory Structure of the Mount
When you mount a repo, the mount point typically contains:
| Directory | Content |
|---|---|
/snapshots/ | All snapshots, named by ID (e.g., d8f3e2a1/) |
/snapshots/latest/ | A symbolic link to the absolute latest snapshot |
/hosts/ | Snapshots organized by the machine they came from |
/tags/ | Snapshots organized by their custom labels |
/ids/ | Every snapshot ID as a folder |
Key Flags
| Flag | Description |
|---|---|
--allow-other | Allow other users to access the mount (requires user_allow_other in /etc/fuse.conf) |
--owner-root | Force all files in the mount to be owned by root |
--snapshot-template | Customize how snapshot folders are named (default is ID) |
--verbose / -v | Show files being accessed in real-time |
Practical Examples
1. Recovering a Single File via cp
No need to run restic restore. Just copy the file directly.
cp /mnt/restic/snapshots/latest/etc/nginx/nginx.conf /tmp/recovered-config.conf
2. Searching for a Lost File with find
Use standard Linux search tools across your entire backup history.
find /mnt/restic/snapshots -name "lost-report.docx"
3. Comparing Two Dates Visually
Open your file manager (Nautilus, Dolphin, Finder) and point it to the mount point to see what changed between folders.
nautilus /mnt/restic/snapshots
restore vs mount
| feature | restore | mount |
|---|---|---|
| Speed | Maximum (Optimized for throughput) | Variable (Limited by FUSE & Network) |
| Disk Space | Needs enough space for the full restore | Uses almost zero disk space |
| Visibility | You see files only after extraction | You see everything instantly |
| Platform | Works everywhere | Requires FUSE (Linux/macOS) |
To use mount, you MUST have FUSE installed on your system.
- Ubuntu/Debian:
sudo apt install fuse - macOS: Install
macFUSE. - Windows: Not natively supported (use WSL2).
Common Pitfalls
| Pitfall | Consequence | Prevention |
|---|---|---|
| High Latency | Exploring cloud-based repo (S3) feels very laggy. | Use ls -l sparingly; use ls without details to speed up directory listing. |
| Forgetting to Unmount | Shell stays locked or mount point becomes "Transport endpoint is not connected." | Unmount gracefully with Ctrl+C or fusermount -u /mountpoint. |
| Large Folder Metadata | Browsing a folder with 1 million small files can take minutes to load. | Be patient or use restic find instead. |
Examples with Output
1. Standard Mount
Command:
restic mount /mnt/restic
Output:
repository a7b2c9d opened successfully, password is correct
Now serving the repository at /mnt/restic
When finished, quit with Ctrl-c or umount the mountpoint.
2. Allow Other Users (Shared Access)
By default, FUSE mounts are only visible to the user who ran the command. Command:
restic mount /mnt/restic --allow-other
Output:
repository a7b2c9d opened successfully, password is correct
Now serving the repository at /mnt/restic
When finished, quit with Ctrl-c or umount the mountpoint.
3. Mount with Ignore Check
Skips the initial repository lock check (risky but faster if you know it's safe). Command:
restic mount /mnt/restic --no-lock
Output:
repository a7b2c9d opened successfully, password is correct
Now serving the repository at /mnt/restic
Don't forget to unmout the mountpoint when finished!
4. Custom Snapshot Template
Organize snapshots by year/month/day in the mount point. Command:
restic mount /mnt/restic --snapshot-template "2006/01/02_15-04-05"
Output:
repository a7b2c9d opened successfully, password is correct
Now serving the repository at /mnt/restic
When finished, quit with Ctrl-c or umount the mountpoint.
5. Listing the Mount (Separate Terminal)
Command:
ls -F /mnt/restic/
Output:
hosts/ ids/ snapshots/ tags/
What's Next?
If you can't install FUSE, use restic ls to browse files in the terminal.