Pick the Right Vagrant Synced Folder Type for Your VM

The problem: your guest is slow at small files

You run vagrant up, the virtual machine boots, and your application starts. Then you run npm install, composer install, or another package manager inside the guest, and it crawls. Thousands of tiny files move across the synced folder, file watchers miss changes, and the VM feels sluggish even though the host is idle.

The cause is often the default synced folder. Vagrant mounts synced folders automatically between your host and guest. On the VirtualBox provider, the default type is VirtualBox shared folders. It works for two-way synchronization, but it can slow down significantly with many small files or frequent writes.

You do not have to keep the default. Vagrant supports several synced folder types, and the right choice depends on which direction files move, your host operating system, and how file-heavy your workload is.

How the three main types behave

Vagrant's synced_folder directive controls the type with the type option. The three common choices are:

Type	Direction	Best for	Host requirements	Guest requirements
VirtualBox shared folders	Two-way	General use, light file traffic	VirtualBox provider	Guest additions or equivalent kernel modules
NFS	Two-way	File-heavy workloads, package manager caches	NFS server support (built in on most Linux and macOS hosts)	Root access to mount; Vagrant handles this automatically
rsync	One-way, host to guest by default	Hosts without NFS, read-only guest code	rsync installed	rsync installed

NFS synced folders generally outperform VirtualBox shared folders for file-heavy workloads, but they need an NFS server on the host and root access inside the guest for mounting. rsync copies files from host to guest on provisioning and on demand; it is one-way by default, so writes inside the guest are not reflected back to the host. VirtualBox shared folders require guest additions or equivalent kernel modules.

Worked example: switch to NFS

Run these commands in your project directory on the host as a normal user. Vagrant may ask for your password to configure host NFS exports and to mount the filesystem inside the guest.

# Edit Vagrantfile in your project root
# Example: replace the default synced folder with NFS
Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
  config.vm.synced_folder ".", "/home/vagrant/app",
    type: "nfs",
    mount_options: ["rw", "vers=4", "tcp"]
end

Then apply the change:

vagrant reload

Changing the synced folder type remounts the guest filesystem, so a reload is required. To roll back, change type back to virtualbox (or remove it to restore the provider default) and run vagrant reload again.

After the guest starts, verify the active mount from inside the VM:

vagrant ssh
mount | grep vagrant

Look for a line showing type nfs. If you see type vboxsf, the guest is still using VirtualBox shared folders. With rsync, the folder is not mounted as a filesystem, so mount | grep vagrant may return nothing for that synced folder.

Permission problems often appear when the mounted filesystem's owner does not match the user running the application. Inside the guest, run id to see your uid and gid, then compare it to the ownership of the mounted directory. If they differ, adjust the Vagrantfile mount options or the application user, then reload.

Trade-offs and limitations

• NFS is not native on all Windows hosts. It may require WSL2 or third-party NFS components. If your host cannot run an NFS server, NFS is not a practical choice.
• rsync-auto polls for changes. Enabling automatic rsync can introduce noticeable latency or CPU usage on large projects.
• VirtualBox shared folders degrade with many small files. Package manager caches and frequent writes are common culprits.
• Changing type after vagrant up requires vagrant reload. There is no live remount without restarting the VM.

How to decide

1. Do you need two-way sync? If yes, choose VirtualBox shared folders or NFS.
2. Is the workload file-heavy (many small files, caches, watchers)? If yes, prefer NFS if your host supports it.
3. Does your host lack NFS support? Use rsync for one-way host-to-guest code, or accept VirtualBox shared folders for lighter traffic.
4. After changing synced_folder, run vagrant reload and confirm with mount | grep vagrant inside the guest.

Start with the default, measure your actual file operations, and switch only if the default is the bottleneck. The synced folder type is a Vagrantfile setting, not a provider commitment, so you can revisit it as your project grows.