by adrienkohlbecker

adrienkohlbecker / vagrant-fsnotify

Forward filesystem change notifications to your Vagrant VM

126 Stars 12 Forks Last release: Not found MIT License 55 Commits 11 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:


Forward filesystem change notifications to your Vagrant VM.


Some filesystems (e.g. ext4, HFS+) have a feature of event notification. Interested applications can subscribe and are notified when filesystem events happen (e.g. a file was created, modified or deleted).

Applications can make use of this system to provide features such as auto-reload or live updates. For example, Jekyll regenerates the static website and Guard triggers a test run or a build when source files are modified.

Unfortunately, Vagrant users have a hard time making use of these features when the application is running inside a virtual machine. When the file is modified on the host, the event is not propagated to the guest and the auto-reload never happens.

There are several bug reports related to this issue:

There are two generally accepted solutions. The first is fall back to long polling, the other is to forward the events over TCP. The problem with long polling is that it's painfully slow, especially in shared folders. The problem with forwarding events is that it's not a general approach that works for any application.


proposes a different solution: run a process listening for filesystem events on the host and, when a notification is received, access the virtual machine guest and
the file in there (or
followed by a
in case of file removals), causing an event to be propagated on the guest filesystem.

This leverages the speed of using real filesystem events while still being general enough to don't require any support from applications.


Due to the nature of filesystem events and the fact that

, the events are triggerred back on the host a second time. To avoid infinite loops, we add an arbitrary debounce of 2 seconds between
-ing the same file. Thus, if a file is modified on the host more than once in 2 seconds the VM will only see one notification. If the second trigger on the host or this arbitrary debounce is unacceptable for your application,
might not be for you.


is a Vagrant plugin and can be installed by running:
$ vagrant plugin install vagrant-fsnotify

Vagrant version 1.7.3 or greater is required.


Basic setup


synced folder configuration, add the
fsnotify: true
option. For example, in order to enable
for the the default
shared folder, add the following:
config.vm.synced_folder ".", "/vagrant", fsnotify: true

When the guest virtual machine is up, run the following:

$ vagrant fsnotify

This starts the long running process that captures filesystem events on the host and forwards them to the guest virtual machine.

Run automatically on vagrant up

To have

vagrant fsnotify
start automatically with your guest, you can use triggers. Add this to your
  config.trigger.after :up do |t| = "vagrant-fsnotify" = { inline: "vagrant fsnotify" }

Now, whenever you run

vagrant up
vagrant fsnotify
will be run as well. Learn more at

Multi-VM environments

In multi-VM environments, you can specify the name of the VMs targeted by

$ vagrant fsnotify   ...

Excluding files

To exclude files or directories from being watched, you can add an

option, which takes an array of strings (matched as a regexp against relative paths):
config.vm.synced_folder ".", "/vagrant", fsnotify: true,
                                         exclude: ["path1", "some/directory"]

This will exclude all files inside the

. It will also exclude files such as

Guest path override

If your actual path on the VM is not the same as the one in

, for example when using
, you can use the
config.vm.synced_folder ".", "/vagrant", fsnotify: true,
                                         override_guestpath: "/real/path"

This will forward a notification on

instead of

Select filesystem events

By default, when the

key in the
is configured with
, all filesystem events are forwarded to the VM (i.e. file creation, modification and removal events). If, instead, you want to select only a few of those events to be forwarded (e.g. you don't care about file removals), you can use an Array of Symbols among the following options:

For example, to forward only added files events to the default

folder, add the following to the
config.vm.synced_folder ".", "/vagrant", fsnotify: [:added]


To hack on

, you need a recent ruby and virtualbox installed.

Then, after cloning the repo: ```shell

install development gems

bundle install

run vagrant commands by prefixing them with
bundle exec
to run with the plugin installed from source

this will launch a basic ubuntu VM and monitor file changes on the current directory

bundle exec vagrant up

make changes to the code

vim lib/vagrant-fsnotify/command-fsnotify.rb ...

relaunch the process to activate your changes

bundle exec vagrant fsnotify ```

Original work

This plugin used

by @smerill and the Vagrant source code as a starting point.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.