Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Networking and Synced Folders

Synced Folders

Share files between host and VM with Vagrant synced folders: the default /vagrant mount, VirtualBox, NFS, rsync and SMB types, options and performance tips.

The best part of a Vagrant workflow is editing code in your favorite editor on your own computer while it runs inside the VM. Synced folders make that possible: a directory on the host appears at a path inside the guest, and changes show up on the other side. By default Vagrant shares the project folder as /vagrant. This lesson explains the available sync types, their trade-offs, and how to fix permission and performance problems.

The default share and how to define more

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"

  # the default, written out explicitly
  config.vm.synced_folder ".", "/vagrant"

  # your code in a different guest path
  config.vm.synced_folder "./src", "/srv/app"

  # a folder outside the project (absolute host path)
  config.vm.synced_folder "~/datasets", "/data", create: true
end

The first argument is the host path (relative paths start at the Vagrantfile), the second the guest path. create: true makes the host folder if it does not exist. To remove the default share, for security or speed:

Ruby
config.vm.synced_folder ".", "/vagrant", disabled: true

Remember that the guest can write to your host files through the share. A script in the VM with a bug (rm -rf /vagrant/*) deletes your project. Keep Git commits and backups.

Sync types

Vagrant chooses a type automatically, or you set it with type:. Each has different strengths.

Type How it works Direction Best for Watch out
virtualbox VirtualBox shared folders (vboxsf) using Guest Additions Two-way, live Default on VirtualBox; simple use Slow for many small files; symlinks restricted on Windows
nfs The host exports the folder over NFS Two-way, live Fast, Linux and macOS hosts Needs a private network, root rights on the host, NFS tools
rsync Copies files with rsync at up and when you ask One-way, host to guest Fast guest-side I/O; works everywhere; no Guest Additions Changes in the guest do not return; needs vagrant rsync
smb Windows file sharing Two-way, live Windows hosts, Hyper-V provider Needs admin rights and credentials
virtiofs / 9p Libvirt/KVM shares Two-way, live libvirt provider Needs provider configuration
flowchart TD
    A{"Host and provider?"} -->|"Windows + VirtualBox"| B["virtualbox (default)"]
    A -->|"Windows + Hyper-V"| C["smb"]
    A -->|"Linux or macOS, want speed"| D["nfs"]
    A -->|"Need native guest I/O speed / no Guest Additions"| E["rsync"]
    A -->|"Linux + libvirt"| F["virtiofs or 9p"]

A quick decision tree for sync types.

VirtualBox shared folders

The default type works out of the box if the box includes VirtualBox Guest Additions. If it does not, you see a message such as "The VirtualBox Guest Additions on this VM do not match the installed version" or the mount fails with /sbin/mount.vboxsf: command not found. The plugin vagrant-vbguest (see the Providers and Plugins chapter) installs matching Guest Additions automatically.

Fine control over permissions:

Ruby
config.vm.synced_folder ".", "/vagrant",
  owner: "vagrant", group: "www-data",
  mount_options: ["dmode=775", "fmode=664"]

Files in a shared folder carry the permissions given by the mount, not those on the host. That is why chmod inside /vagrant appears to do nothing, and why a web server may complain that it cannot write to storage/. Setting owner, group and mount_options fixes it.

NFS

NFS is much faster than VirtualBox shared folders for large trees (a PHP framework, node_modules), but it needs setup:

Ruby
config.vm.network "private_network", ip: "192.168.56.10"
config.vm.synced_folder ".", "/vagrant", type: "nfs", nfs_version: 4, nfs_udp: false

Vagrant edits /etc/exports on the host to export the folder and asks for your password (sudo). A private network is required because the guest connects to the host's address on it. On Windows there is no built-in NFS server; use smb or rsync, or the plugin vagrant-winnfsd, which is old and unmaintained. You can allow passwordless sudo for the Vagrant NFS commands to avoid the prompt on each up.

rsync

The rsync type copies the folder into the guest when the machine starts. The guest then works on a normal local filesystem, which is as fast as it gets:

Ruby
config.vm.synced_folder ".", "/vagrant",
  type: "rsync",
  rsync__exclude: [".git/", "node_modules/", "vendor/", ".vagrant/"],
  rsync__args: ["--verbose", "--archive", "--delete", "-z"]

It is one way: host to guest. To push changes you run vagrant rsync, or you keep vagrant rsync-auto running in a second terminal, which watches the host folder and syncs on every save. Edits made in the guest are overwritten at the next sync (because of --delete). That is perfect for "run my code in a clean Linux", and wrong for "generate files in the VM and use them on the host". For a reverse direction, use the plugin vagrant-rsync-back, or a second synced folder of another type.

SMB

On Windows hosts, type: "smb" shares through Windows file sharing. It needs an elevated (administrator) prompt and asks for your Windows user and password, which can also be set with smb_username and smb_password (not recommended in a committed file). It is the usual choice for the Hyper-V provider.

Performance and permissions: practical tips

  1. Exclude heavy folders. Install node_modules, Composer vendor or Python virtual environments inside the guest in a non-shared path such as /home/vagrant/app-node_modules and symlink or bind-mount them. Shared folders are slow for thousands of small files.
  2. Choose the right type for the work: NFS or rsync for builds, VirtualBox for casual use.
  3. Do not run databases on shared folders. SQLite or PostgreSQL data directories on a synced folder can corrupt or be unbearably slow; keep them on the guest's own disk.
  4. Symlinks on Windows with VirtualBox: creating symlinks in a shared folder requires enabling them (VBoxManage setextradata VM VBoxInternal2/SharedFoldersEnableSymlinksCreate/<share> 1) and running the terminal as administrator. A common workaround is installing dependencies outside the share.
  5. Clock and file times: if builds act strangely, check that host and guest clocks agree; Guest Additions sync the time.
  6. Case sensitivity: Linux is case-sensitive, Windows and macOS usually are not. A path that works on your host may break in production.

What each type does to a changed file

The next stand-in is Ruby that models the direction of change for the three main types, using two hashes as the host and guest folders. It is not a real filesystem, but it shows why one-way rsync behaves differently from a live share.

Ruby Live share versus one-way rsync (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Checking mounts

  • vagrant ssh -c "mount | grep vagrant" shows the type and options in use.
  • vagrant ssh -c "ls -la /vagrant" shows owner and permissions as the guest sees them.
  • A mount that silently fails leaves an empty /vagrant. Check vagrant up output for lines starting with "Mounting shared folders".
  • Disable and re-enable a share by editing the Vagrantfile and running vagrant reload. Synced folder changes need a reload.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which synced folder type is one-way (host to guest) and needs vagrant rsync or rsync-auto to update?

    The rsync type copies host files into the guest; edits in the guest do not come back.
  2. 2. Why are files in /vagrant sometimes owned by the vagrant user with fixed permissions even after chmod?

    Shared filesystems such as vboxsf take permissions from mount options rather than per-file chmod.
  3. 3. What does NFS require that the default VirtualBox share does not?

    Vagrant exports the folder from the host, so the guest needs a private network address to mount it, and the host needs an NFS server.
  4. 4. Where should you keep a database data directory?

    Shared folders can be slow and unsafe for databases; keep data on the guest's native filesystem.

Summary

  • A synced folder shares a host directory with the guest; /vagrant is the default.
  • Types: virtualbox (default, simple), nfs (fast, needs private network), rsync (one-way, fastest in the guest), smb (Windows).
  • Set owner, group and mount_options for permissions; exclude heavy folders for speed.
  • Do not keep databases or node_modules on slow shares.
  • Apply changes with vagrant reload; use vagrant rsync-auto for continuous one-way syncing.

Next: SSH and Access