Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 Β· Troubleshooting and Alternatives

Performance and Windows Issues

Speed up Vagrant machines: choose faster synced folder types, give the right resources, avoid slow I/O, and fix Windows problems with symlinks, paths and line endings.

A Vagrant machine that feels slow is rarely short on CPU. The usual culprit is file access across the shared folder, followed by too little memory and bad defaults. Windows adds its own set of problems: symlinks, long paths, line endings and hypervisor conflicts. This lesson shows how to find the bottleneck and fix it.

Find the bottleneck first

Measure before changing anything. Inside the guest:

TEXT
$ vagrant ssh
$ time (cd /vagrant && find . -type f | wc -l)     # shared folder
$ time (cd ~ && find . -type f | wc -l)            # guest's own disk
$ free -m                                          # memory and swap
$ top                                              # CPU
$ vmstat 1 5                                       # I/O wait (the 'wa' column)

If a command takes ten times longer under /vagrant than in the guest's home directory, the shared folder is the problem. If free -m shows swap in use, the guest needs more memory. If wa in vmstat is high, the disk is the limit.

Synced folder types and speed

Different mechanisms trade speed against convenience.

Type Speed Two-way live sync Notes
VirtualBox shared folders (default) Slow for many small files Yes Needs matching Guest Additions
NFS Fast Yes Needs NFS on the host; private network required; Linux and macOS hosts
rsync Fast (files are local in the guest) No, one-way by default Use vagrant rsync-auto to watch for changes
SMB Medium Yes Windows hosts; asks for credentials
Ruby
# NFS (Linux / macOS host)
config.vm.network "private_network", ip: "192.168.56.20"
config.vm.synced_folder ".", "/vagrant", type: "nfs", nfs_version: 4, nfs_udp: false

# rsync with exclusions
config.vm.synced_folder ".", "/vagrant", type: "rsync",
  rsync__exclude: [".git/", "node_modules/", "vendor/"],
  rsync__auto: true

Excluding directories with thousands of files (node_modules, vendor, .git) is one of the best speedups, because those are the files that make shared folders crawl. Better still, keep such directories on the guest's own disk, and bind them over the project path.

Ruby
config.vm.provision "shell", inline: <<~SH
  mkdir -p /home/vagrant/node_modules
  mkdir -p /vagrant/node_modules
  mount --bind /home/vagrant/node_modules /vagrant/node_modules
SH

Dependency installs then run at native disk speed. The details are covered in the synced folders chapter.

Give the guest the right resources

  • Memory: 2 GB is a good default for a typical web stack; databases and Java want more. Watch free -m for swap.
  • CPUs: two cores often beat one by a lot; more than half of your physical cores rarely helps.
  • Linked clones (vb.linked_clone = true) make clusters create quickly.
  • Paravirtualization: for VirtualBox, vb.customize ["modifyvm", :id, "--paravirtprovider", "kvm"] helps Linux guests, and --nictype1 virtio speeds up the network.
  • DNS slowness: if apt-get or curl pause for several seconds before connecting, enable the host resolver: vb.customize ["modifyvm", :id, "--natdnshostresolver1", "on"].

See tuning the VirtualBox provider for the full list.

Speeding up vagrant up

  • Use a custom box with the slow installs baked in (packaging boxes).
  • Set config.vm.box_check_update = false to skip the version check.
  • Use a package cache: point apt at a local proxy, or mount /var/cache/apt from a persistent location shared between machines.
  • Make provisioning idempotent and conditional, so re-runs skip finished work:
Ruby
config.vm.provision "shell", inline: <<~SH
  if ! command -v nginx >/dev/null; then
    apt-get update && apt-get install -y nginx
  fi
SH

Windows: the usual problems

Hyper-V versus VirtualBox

Hyper-V (also used by WSL 2 and Docker Desktop) can prevent VirtualBox from using hardware virtualization at full speed. Symptoms: very slow guests, or errors such as VERR_NEM_VM_CREATE_FAILED. Fix by using the Hyper-V provider, or by turning off the Windows features (bcdedit /set hypervisorlaunchtype off) when you need VirtualBox. Recent VirtualBox versions work alongside Hyper-V but run slower.

Creating symlinks inside a VirtualBox shared folder fails by default on Windows, which breaks npm install for some projects. Options:

  • enable them: vb.customize ["setextradata", :id, "VBoxInternal2/SharedFoldersEnableSymlinksCreate/vagrant", "1"] (and start your terminal as administrator);
  • use npm install --no-bin-links;
  • or move node_modules to the guest's disk as shown above.

Line endings

Windows Git converts to CRLF, which breaks shell scripts in the guest. Enforce LF with .gitattributes as described in sharing a Vagrantfile in Git.

Path length and special characters

Keep the project path short and free of spaces and non-ASCII characters (C:\work\myapp, not C:\Users\JΓΌrgen MΓΌller\Documents\My Projects\...). Long paths hit the 260-character limit in some tools.

Terminals and SSH

vagrant ssh needs an SSH client. Git for Windows provides one, and Windows 10 and 11 include OpenSSH. If a prompt looks garbled, use Windows Terminal or Git Bash, not an old console.

Antivirus and file watchers

Real-time antivirus scanning of the VM disk or shared folders can slow things a lot. Exclude the VirtualBox VM folder and your project from scanning if your policy allows it. File-change watchers (webpack, Jekyll) do not see changes made on a shared folder in some combinations; switch the tool to polling mode.

A stand-in: measuring the effect of exclusions

You can see why excluding node_modules helps with arithmetic. This Ruby model counts how many files an rsync would have to look at with and without exclusions. The numbers are invented; the point is the shape of the saving.

Ruby What does rsync have to scan?

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.

Common mistakes

  • Blaming the CPU when the shared folder is the bottleneck.
  • Giving the guest more memory than the host can spare, which makes both swap.
  • Using NFS on a Windows host. Use SMB or rsync there.
  • Keeping the project under a long, spaced path.
  • Running VirtualBox and Hyper-V together without knowing the cost.

Check your understanding

Quick check Β· 4 questions

of 4 answered You scored / 4 Β· perfect!

  1. 1. Why is a directory like node_modules so costly in a default shared folder?

    Many small file operations are what shared folders are slowest at.
  2. 2. Which synced folder type copies files into the guest so they are read at native disk speed?

    rsync copies files to the guest disk. The trade-off is one-way sync unless rsync-auto is running.
  3. 3. On a Windows host, which action helps most against CRLF-related script failures?

    Forcing eol=lf ensures scripts keep Unix line endings after checkout.
  4. 4. free -m shows heavy swap use inside the guest. What does this suggest?

    Swap activity means the guest has run out of RAM.

Summary

  • Measure first: compare timing under /vagrant with the guest's own disk, and watch memory and I/O wait.
  • Prefer NFS (Unix hosts), SMB or rsync over default shared folders for large trees, and exclude or relocate dependency directories.
  • Allocate sensible memory and CPUs and use linked clones, a custom box and idempotent provisioning for faster up.
  • On Windows, watch for hypervisor conflicts, symlinks, line endings, long paths and antivirus.

Next: Vagrant versus Docker and alternatives