At some point almost every Proxmox user runs into the same wall: the local disk on the Proxmox host fills up, or you've got a NAS sitting on the network doing nothing useful, and you'd rather store your ISOs, backups, or VM disks somewhere else. NFS is usually the easiest way to bridge that gap, and it's a lot less intimidating than it sounds once you've done it once.
This guide walks through connecting a Proxmox VE host to an NFS share step by step — through the GUI and the command line — and covers the mistakes that usually cause it to fail silently or half-work.
What You Will Learn
You'll learn what NFS actually is and why it's a common choice for Proxmox storage, how to add an NFS share as a storage pool through both the web interface and pvesm, what each configuration field actually controls, and how to fix the handful of errors that show up almost every time someone tries this for the first time.
What Is This Feature?
NFS stands for Network File System. It's a protocol, originally built by Sun Microsystems and now a Linux/Unix standard, that lets a computer share a folder over the network so other machines can mount it and use it as if it were a local drive. A NAS box, a TrueNAS server, or even another Linux machine running the nfs-kernel-server package can all act as an NFS server.
When you add NFS storage in Proxmox, you're telling the Proxmox host: "there's a folder on that other machine, go mount it, and let me use it to store VM disks, ISOs, backups, or whatever else." Proxmox handles the mounting automatically in the background — you never have to run a manual mount command yourself once it's configured.
It's worth knowing where NFS sits relative to other storage options you'll see in Proxmox. Here's a quick comparison:
| Storage Type | Where It Lives | Good For |
|---|---|---|
| Local (Directory/LVM) | Disk inside the Proxmox host | Fastest access, but tied to one node |
| NFS | Remote server over the network | Shared access across multiple nodes, easy to set up |
| ZFS over iSCSI / Ceph | Distributed or block-level remote storage | Clusters needing high availability and redundancy |
NFS sits in a comfortable middle ground: simpler to configure than Ceph, and unlike purely local storage, any node in a cluster can reach the same share.
Why Would You Use It?
The most common reason is running out of local disk space, especially for backups and ISO files, which tend to pile up fast and don't need the fastest possible storage. Dumping backups on a separate NAS also means a dead Proxmox boot disk doesn't take your backups down with it — which, if you've never lost a backup that way, is worth avoiding.
The second big reason is clustering. If you're running more than one Proxmox node, local storage on each node is isolated — VM disks stored locally can't easily migrate between hosts. Point every node at the same NFS share, and suddenly they can all see the same VM disk images, ISOs, and backup files, which is what makes live migration between nodes practical without extra replication setup.
I'll be upfront about the tradeoff: NFS performance depends entirely on your network and your NFS server's disks. A VM running its main disk off a slow NFS share over a 1 Gbps link will feel noticeably sluggish compared to local SSD storage. For ISOs, backups, and templates, that doesn't matter. For a database VM's primary disk, it might.
Prerequisites
- A working Proxmox VE host (this guide applies to 8.x and 9.x — the process hasn't changed in years).
- An NFS server already sharing a folder on your network — this could be a NAS (Synology, QNAP, TrueNAS) or a Linux box running
nfs-kernel-server. - Network connectivity between the Proxmox host and that server — test with a basic
pingif you're not sure. - The export's permissions configured on the NFS server side to allow your Proxmox host's IP address to connect. This is set up on the NFS server, not in Proxmox, and it's the single most common thing people forget.
You don't need to install any NFS client packages yourself — Proxmox VE ships with the NFS client tools already installed.
Step-by-Step Tutorial
Step 1: Confirm the Export Is Reachable
Before touching the Proxmox GUI, it's worth confirming the share is actually visible from the host. SSH into your Proxmox node and run:
showmount -e 192.168.1.50Replace the IP with your NFS server's address. This lists every export that server is offering. If the command hangs or refuses the connection, the problem is on the NFS server's side — usually a firewall or an export permission that doesn't include your Proxmox host's IP — and no amount of clicking around in the Proxmox GUI will fix that.
Step 2: Add the Storage Through the GUI
In the Proxmox web interface, click Datacenter in the left-hand tree, then go to Storage → Add → NFS.
Fill in the fields:
- ID — a short name you're choosing for this storage pool inside Proxmox, like
nas-backups. This is just a label; it doesn't need to match anything on the NFS server. - Server — the IP address of your NFS server. Using an IP rather than a hostname avoids depending on DNS being available, which matters if DNS ever goes down and your storage needs to keep working.
- Export — once you type a valid server address, Proxmox queries it and shows a dropdown of available exports. Pick the one you want, rather than typing it manually.
- Content — tick the checkboxes for what you'll store here: Disk image for VM virtual disks, ISO image for installer ISOs, VZDump backup file for backups, Container template for LXC templates.
- Nodes — leave this on All unless you specifically want only certain nodes in a cluster to use this storage.
Click Add. Proxmox mounts the share immediately, and you should see it appear under Datacenter → Storage with a green checkmark.
Step 3: Add the Storage From the Command Line (Alternative)
If you prefer the CLI, or you're scripting a setup across multiple nodes, the equivalent command is:
pvesm add nfs nas-backups --server 192.168.1.50 --export /volume1/proxmox-backups --content backup,isoHere nas-backups is the storage ID, --server points to the NFS host, --export is the exact path on that server, and --content lists what this storage will hold, comma-separated.
Step 4: Verify It's Actually Mounted
Run:
pvesm statusYou should see your new storage listed with a status of active and a usable amount of space under the avail column. If it says inactive, the mount failed even though the storage entry was created — the config exists in Proxmox but nothing is actually connected.
You can also check the underlying mount directly:
df -h | grep pveNFS storage in Proxmox is mounted under /mnt/pve/<storage-id> by default, so you should see that path listed with real disk space, not zero.
Commands Explained
| Command | What it does |
|---|---|
showmount -e SERVER_IP | Lists the NFS exports a given server is currently offering, without mounting anything. |
pvesm add nfs ID --server IP --export PATH --content TYPES | Creates a new NFS storage entry in Proxmox and mounts it under /mnt/pve/ID. |
pvesm status | Shows every configured storage pool, whether it's currently active, and how much space is free. |
pvesm remove ID | Removes a storage pool's configuration from Proxmox (does not delete the data on the NFS server itself). |
df -h | Standard Linux command showing disk usage for all mounted filesystems, including NFS mounts. |
Common Errors
"mount error: access denied by server" — this means the NFS server itself is rejecting the connection, almost always because the export's allowed client list on the NFS server doesn't include your Proxmox host's IP address. Fix it on the NFS server side, not in Proxmox.
"Connection timed out" when adding the storage — usually a firewall blocking NFS ports (2049, plus the portmapper on 111 for older NFSv3 setups) somewhere between the Proxmox host and the NFS server.
Storage shows up but is greyed out with a question mark icon — the storage config exists, but Proxmox currently can't reach the mount. This is common right after the NFS server reboots, or if its IP address changed.
"exportfs: /path does not support NFS export" — this happens on the NFS server side, not in Proxmox, and usually means the export path either doesn't exist or isn't properly listed in the server's own export configuration (/etc/exports on Linux NFS servers).
Troubleshooting
- Start with
showmount -e SERVER_IPfrom the Proxmox host every time something's not working. If that fails, nothing downstream will succeed either, so there's no point troubleshooting Proxmox settings yet. - Check
pvesm statusfor the storage's actual state. "Active" but zero space available usually points to a permissions problem on the export itself, not a connectivity issue. - If the mount worked once and then dropped, check whether the NFS server's IP address changed, or whether it went through a reboot and came back with the export configuration reset.
- Look at the system log with
journalctl -xeright after a failed mount attempt — it usually names the exact NFS error code involved rather than Proxmox's generic failure message. - Test a manual mount outside of Proxmox to isolate the problem:
mount -t nfs 192.168.1.50:/volume1/proxmox-backups /mnt. If that fails too, it confirms the issue is with NFS itself, not Proxmox's handling of it.
Best Practices
Use a static IP or a DHCP reservation for your NFS server. If its address changes, every Proxmox node pointing at it loses its storage until you manually fix the config, and that's an annoying thing to discover during a backup job at 2 a.m.
Separate your content types across different NFS exports where it makes sense — one export for backups, another for ISOs — rather than dumping everything into a single folder. It keeps permissions cleaner and makes it easier to reason about how much space each category is actually using.
Don't put a VM's primary disk on NFS unless you've actually tested the performance for your workload. It works, and plenty of people run production VMs this way successfully, but it's worth benchmarking rather than assuming it'll be fine.
If you're running a cluster, add the NFS storage with the same ID and settings on every node rather than configuring it differently per node — this is what lets live migration move a VM between hosts without needing to copy its disk.
Frequently Asked Questions
Is NFS storage shared automatically across all my Proxmox nodes in a cluster?
Yes, as long as you add it as shared storage (the default when using the GUI) and every node can reach the NFS server over the network. That shared visibility is exactly what enables live migration.
Can I store VM disks on NFS, or is it only for backups and ISOs?
You can store VM disks on NFS — tick Disk image under Content when adding the storage. Just be aware that performance depends heavily on your network speed and the NFS server's own disks.
Do I need to configure anything on the NFS server before adding it in Proxmox?
Yes. The export needs to already exist and explicitly allow your Proxmox host's IP address to connect. Proxmox can't create the export for you — that configuration lives entirely on the NFS server.
What's the difference between NFSv3 and NFSv4, and does it matter here?
NFSv4 adds better security and performance features over NFSv3, including built-in Kerberos support and a single well-defined port (2049) instead of relying on the older portmapper service. Proxmox supports both; NFSv4 is the better default unless your NFS server only offers NFSv3.
My storage worked fine and then went inactive after a reboot. Why?
This usually means the NFS server wasn't reachable yet when Proxmox tried to remount the share at boot — a common issue if the NFS server and Proxmox host both restart around the same time. It typically resolves itself once the NFS server is fully back online; Proxmox will retry the mount automatically.
Conclusion
NFS is one of the more approachable ways to get shared, network-based storage working in Proxmox, especially compared to setting up something like Ceph. Most of the friction people hit isn't really a Proxmox problem — it's an NFS export permission issue sitting on the server side, waiting to be found with a simple showmount command before you even open the Proxmox GUI.
Get the export permissions right first, and the actual Proxmox side of this takes about two minutes.