Proxmox Directory Storage: The Structure No One Explains

If you’ve ever found yourself confused why Proxmox is “hiding” your ISO files or not listing them in the GUI, you’re not alone. The behavior is not a bug—it’s by design, just very poorly documented.

This guide documents what Proxmox expects when using directory (dir) storage types—especially on ZFS—so everything shows up and works cleanly.

🔍 The Hidden Directory Structure

When you point dir storage to a path, Proxmox does not use that folder directly. Instead, it creates specific subdirectories inside that path depending on content type:

✅ Correct Setup Example

1. Create a ZFS Dataset:

zfs create zfs-ssd/proxmox-data

This will be mounted at:

/zfs-ssd/proxmox-data/

2. Configure storage.cfg:

dir: iso-storage
    path /zfs-ssd/proxmox-data
    content iso

dir: vztemplate-storage
    path /zfs-ssd/proxmox-data
    content vztmpl

dir: backup-storage
    path /zfs-ssd/proxmox-data
    content backup

dir: snippet-storage
    path /zfs-ssd/proxmox-data
    content snippets

🧠 Important Notes

• DO NOT try to flatten the structure (e.g. putting .iso files directly in /zfs-ssd/proxmox-data/iso/). Proxmox will not see them.
• You can upload files using SCP directly into the correct subfolder (template/iso/, etc.).
• If you upload through the Proxmox GUI, it will place files in these subfolders automatically.
• This applies to all directory storage, whether on ZFS or not.

✅ End Result

When configured properly, the GUI will:

• ✅ Show all ISOs under Datacenter → iso-storage
• ✅ List all LXC templates under vztemplate-storage
• ✅ Let you restore and manage backups under backup-storage
• ✅ Show custom snippets for injection and cloud-init configs

🏁 Conclusion

You don’t need to fight Proxmox. You just need to know where it’s looking.

This guide is now your definitive reference.

— from the PacketRealm Homelab Archives