Vagrant Fsnotify

Forward filesystem change notifications to your Vagrant VM
Alternatives To Vagrant Fsnotify
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
15 hours ago3,734otherC++
Compatibility tool for Steam Play based on Wine and additional components
23 days ago46otherHTML
Metasploitable3 is a VM that is built from the ground up with a large amount of security vulnerabilities.
Workadventure2,983116 hours ago63September 16, 2022474TypeScript
A collaborative web application (virtual office) presented as a 16-bit RPG video game
Redis Windows2,395
4 years ago1Shell
Vagrant redis configuration and the binary releases of MS Open Tech redis port of windows
Rails Dev Box2,046
2 months ago11mitShell
A virtual machine for Ruby on Rails core development
Ansible Vagrant Examples1,988
4 months ago1mit
Ansible examples using Vagrant to deploy to local VMs.
a year ago14mitJavaScript
Staffjoy V2 - all microservices in a monorepo
Vagrant Hostmanager1,450712 years ago35May 18, 201871mpl-2.0Ruby
:pencil: A Vagrant plugin that manages hosts files within a multi-machine environment.
Drupal Vm1,39112110a month ago99May 28, 202116mitJinja
A VM for Drupal development
15 hours ago16gpl-3.0Shell
💻☁📦 The Nextcloud VM (virtual machine appliance), Home/SME Server and scripts for RPi (4). Community developed and maintained.
Alternatives To Vagrant Fsnotify
Select To Compare

Alternative Project Comparisons


Gem Gem

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.


vagrant-fsnotify 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 touch the file in there (or touch followed by a rm 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 vagrant-fsnotify uses touch, the events are triggerred back on the host a second time. To avoid infinite loops, we add an arbitrary debounce of 2 seconds between touch-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, vagrant-fsnotify might not be for you.


vagrant-fsnotify 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

In Vagrantfile synced folder configuration, add the fsnotify: true option. For example, in order to enable vagrant-fsnotify for the the default /vagrant 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 Vagrantfile:

  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 using:

$ vagrant fsnotify <vm-name-1> <vm-name-2> ...

Excluding files

To exclude files or directories from being watched, you can add an :exclude 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 path1 and some/directory. It will also exclude files such as another/directory/path1

Guest path override

If your actual path on the VM is not the same as the one in synced_folder, for example when using vagrant-bindfs, you can use the :override_guestpath option:

config.vm.synced_folder ".", "/vagrant", fsnotify: true,
                                         override_guestpath: "/real/path"

This will forward a notification on ./myfile to /real/path/myfile instead of /vagrant/myfile.

Select filesystem events

By default, when the :fsnotify key in the Vagrantfile is configured with true, 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: :added, :modified and :removed.

For example, to forward only added files events to the default /vagrant folder, add the following to the Vagrantfile:

config.vm.synced_folder ".", "/vagrant", fsnotify: [:added]

Set touch flags

By default, the touch command on the VM will be run with modification flag and access flag, setting both modification and access attributes of the file. If only either flag should be used the :touch param can be set per machine config in the Vagrantfile. The param supports an array with either or both :modification and :access values.

As example, to only set the access attribute of files when they have changed on the host system set the following in the Vagrantfile:

config.fsnotify.touch = [:access]

or for instances and providers

config.vm.define "vm" do |instance|
    instance.fsnotify.touch = [:access]


To hack on vagrant-fsnotify, you need a recent ruby and virtualbox installed.

Then, after cloning the repo:

# 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 vagrant-rsync-back by @smerill and the Vagrant source code as a starting point.

Popular Virtual Machine Projects
Popular Vagrant Projects
Popular Virtualization Categories

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.