Skip to content


Subversion checkout URL

You can clone with
Download ZIP
The Listen gem listens to file modifications and notifies you about the changes.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

Listen Build Status

The Listen gem listens to file modifications and notifies you about the changes.


  • Works everywhere!
  • OS-specific adapters for Mac OS X 10.6+, Linux and Windows.
  • Automatic fallback to polling if OS-specific adapter doesn't work.
  • Detects files modification, addidation and removal.
  • Checksum comparaison for modifications made under the same second.
  • Tested on all Ruby environments via travis-ci.
  • Threadable.


gem install listen


There are two ways you can use Listen.

  1. call with a path params, and define callbacks in a block.
  2. create a listener object usable in an (ARel style) chainable way.

Feel free to give your feeback via Listen issues

Block API'dir/path/to/listen', filter: /.*\.rb/, ignore: '/ignored/path') do |modified, added, removed|
  # ...

"Object" API

listener ='dir/path/to/listen')
listener = listener.ignore('/ignored/path')
listener = listener.filter(/.*\.rb/)
listener = listener.latency(0.5)
listener = listener.force_polling(true)
listener = listener.polling_fallback_message(false)
listener = listener.change(&callback)
listener.start # enter the run loop

      .polling_fallback_message('custom message')
      .start # enter the run loop

Multiple listeners support available via Thread

listener ='/ignored/path/')
styles   = listener.filter(/.*\.css/).change(&style_callback)
scripts  = listener.filter(/.*\.js/).change(&scripts_callback) { styles.start } # enter the run loop { scripts.start } # enter the run loop


These options can be set through params or via methods (see the "Object" API)

:filter => /.*\.rb/, /.*\.coffee/              # Filter files to listen to via a regexps list.
                                               # default: none

:ignore => 'path1', 'path2'                    # Ignore a list of paths (root directory or sub-dir)
                                               # default: '.bundle', '.git', '.DS_Store', 'log', 'tmp', 'vendor'

:latency => 0.5                                # Set the delay (**in seconds**) between checking for changes
                                               # default: 0.1 sec (1.0 sec for polling)

:force_polling => true                         # Force the use of the polling adapter
                                               # default: none

:polling_fallback_message => 'custom message'  # Set a custom polling fallback message (or disable it with `false`)
                                               # default: "WARNING: Listen fallen back to polling, learn more at"


Listener can also easily be paused/unpaused:

listener ='dir/path/to/listen')
listener.start   # enter the run loop
listener.pause   # stop the run loop and enter the wait loop
listener.unpause # re-enter the run loop

Listen adapters

The Listen gem has a set of adapters to notify it when there are changes. There are 3 OS-specific adapters to support Mac, Linux and Windows. These adapters are fast as they use some system-calls to implement the notifying function.

There is also a polling adapter which is a cross-platform adapter and it will work on any system. This adapter is unfortunately slower than the rest of the adapters.

The Listen gem will choose the best and working adapter for your machine automatically. If you want to force the use of the polling adapter, either use the :force_polling option while initializing the listener or call the force_polling method on your listener before starting it.

Polling fallback

When the OS-specific adapter doesn't work the Listen gem automatically falls back to the polling adapter. Here some things to try to avoiding this fallback:

If it still falling back, feel free to open an issue (and be sure to give all details).

Development Dependency Status

Pull requests are very welcome! Please try to follow these simple rules if applicable:

  • Please create a topic branch for every separate change you make.
  • Make sure your patches are well tested. All specs run with rake spec:portability must pass.
  • Update the Yard documentation.
  • Update the README.
  • Update the CHANGELOG for noteworthy changes.
  • Please do not change the version number.

For questions please join us in our Google group or on #guard (



Thibaud Guillaume-Gentil (@thibaudgg)


Something went wrong with that request. Please try again.