Vagrant 1.5 Feature Preview: Rsync Synced Folders

Vagrant 1.5 Feature Preview: Rsync Synced Folders

Feb 12 2014 Mitchell Hashimoto

Vagrant 1.5 is going to be the biggest release of Vagrant since 1.1, with dozens of new features and improvements coming in. Don't worry, we've also obsessed over stability, so we expect it'll be one of the most stable upgrades, too.

Because Vagrant 1.5 will be so feature-packed, we're doing a series of blog posts that highlight the upcoming features so you know what to look forward to and how to use them. These posts will be weekly on Wednesdays, so keep an eye out for them!

We're going to kick off the series by introducing rsync synced folders. These synced folders offer incredible I/O performance at the expense of a little bit of latency. Read on to learn more.

Introducing Rsync Synced Folders

Rsync synced folders use rsync to sync files to the guest machine. They are configured just as easily as any other synced folder, by just specifying the "rsync" type:

config.vm.synced_folder ".", "/vagrant", type: "rsync"

As long as rsync is installed in both the host and the guest, this will just work. Since rsync is a standard utility for Mac and most Linux distributions, this just works most of the time! For Windows users, msysgit, MinGW, and Cygwin all provide rsync.

As an added benefit, Vagrant 1.5 knows how to install rsync for most major operating systems, and will do this automatically for you by default within the guest machine if rsync cannot be found.

When you execute vagrant up or vagrant reload, Vagrant will sync the data to the guest machine. In addition to these commands, Vagrant has a new command vagrant rsync that will only sync rsync folders that are defined.

Unlike VM shared folders and NFS, rsync is a one-time sync from the host machine to the guest machine. Changes to the folder after the sync is complete won't be visible in the guest machine until you force another sync with a command such as vagrant rsync. Luckily, Vagrant 1.5 will provide a way to auto-sync rsync synced folders.


By default, the folder syncing only happens when you manually execute a vagrant up, vagrant reload, or vagrant rsync. Part of the magic of Vagrant, though, has always been for changes to just appear in the guest machine.

Rsync synced folders don't have this magic property by default because unlike VM shared folders or NFS, rsync doesn't continue to run in the background to propagate any changes. And Vagrant itself doesn't keep any background processes running after it finishes executing, so by default changes won't be seen.

But because this is such a useful feature of Vagrant, Vagrant 1.5 has avagrant rsync-auto command. This command runs forever (until you Ctrl-C), watches any defined rsync synced folders, and automatically syncs changes as you make them.

$ vagrant rsync-auto ==> default: Watching: /home/mitchellh/work/frontend default: Changes! Syncing /vagrant ...

This command uses system-specific APIs to detect file changes, rather than polling the file system. Therefore, this command sits idle most of the time and consumes only a small amount of RAM.

Changes are usually picked up in less than a second, and Vagrant only syncs changes over a compressed connection to use as little bandwidth as possible. As a result, changes appear in the guest machine quite fast.

We realize this workflow is a bit different than what you're used to with Vagrant, but it is a minor change necessitated by the technical differences of rsync versus other available synced folder mechanisms.

Performance and Benefits

Because rsync

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now