Vagrant NFS Synced Folders: Performance, Setup, and Pitfalls

Why NFS synced folders improve performance

Enabling NFS synced folders in Vagrant gives the guest VM near-native file access speed, which is especially noticeable when the project contains many small files or generates large build artifacts. The default VirtualBox shared folder adds overhead for each I/O operation; NFS bypasses that layer by letting the guest mount a directory exported directly from the host's NFS server.

Configuration example

Add the following lines to your Vagrantfile (replace ./project with the host path you want to share):

Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/focal64"
  config.vm.synced_folder "./project", "/vagrant", type: "nfs"
end

Place this file in the root of your project and run vagrant up from a terminal with sufficient privileges to start the VM. Vagrant will automatically start the NFS server on the host (if not already running) and mount the exported folder inside the guest at /vagrant.

Host requirements and setup

• Operating system: Linux or macOS. Windows hosts need a third-party NFS server (e.g., win-nfs) and are not covered by the built-in Vagrant support.
• Packages: On Debian/Ubuntu hosts install nfs-kernel-server and nfs-common; on RHEL/CentOS install nfs-utils. On macOS the NFS server is included but may need to be enabled via sudo nfsd enable.
• Permissions: The host commands that install or start the NFS service require root (sudo). Inside the guest, the nfs-common package must be installed so the VM can act as an NFS client.
• Network: The host-guest network must be private (the default NAT with port forwarding works, but a private network config.vm.network "private_network", type: "dhcp" is recommended for stable NFS mounting).

Verifying the NFS mount

After the VM is booted, log in with vagrant ssh and run:

mount | grep /vagrant

You should see a line indicating the filesystem type is nfs, for example:

10.0.2.2:/vagrant on /vagrant type nfs (rw,addr=10.0.2.2)

On the host, confirm the export list:

showmount -e localhost

The output should include the directory you specified in the Vagrantfile (e.g., /home/user/project).

To check that changes appear instantly, create a test file on the host:

touch ./project/testfile

Then inside the guest run:

ls -l /vagrant/testfile

The file should be present without any noticeable delay.

Limits and common mistakes

• Encryption: NFS traffic is not encrypted. If the host-guest network is not trusted (e.g., a public Wi-Fi), consider tunneling NFS over SSH or using a VPN.
• Reloading after changes: If you modify the synced folder type (e.g., switch from the default to NFS) after the VM has already been created, you must run vagrant reload --provision or destroy and recreate the VM with vagrant up --destroy. Otherwise the old mount persists and you may see "file not found" errors.
• Missing client packages: Forgetting to install nfs-common inside the guest results in a mount failure; the VM will boot but the /vagrant directory will be empty or inaccessible.
• Host server not running: On Linux, if the nfs-kernel-server service is not active, Vagrant will timeout while trying to export the folder. Start it with sudo systemctl start nfs-kernel-server (or the equivalent for your distro).
• Performance on slow networks: If the host-guest link is throttled (e.g., VPN with low bandwidth), the NFS advantage may disappear; compare copy times of a large file using the default VirtualBox shared folder versus NFS to verify the gain.