Skip to content
Go to file


Failed to load latest commit information.


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

Listen is currently accepting more maintainers. Please read this if you're interested in joining the team.

Development Status Gem Version Code Climate Coverage Status


  • OS-optimized adapters on MRI for Mac OS X 10.6+, Linux, *BSD and Windows, more info below.
  • Detects file modification, addition and removal.
  • You can watch multiple directories.
  • Regexp-patterns for ignoring paths for more accuracy and speed
  • Increased change detection accuracy on OS X HFS and VFAT volumes.
  • Tested on selected Ruby environments via Travis CI. (See .travis.yml for supported/tested Ruby Versions),

Issues / limitations

  • Limited support for symlinked directories (#279):
  • No directory/adapter-specific configuration options.
  • Support for plugins planned for future.
  • TCP functionality was removed in Listen 3.0.0 (#319, #218). There are plans to extract this feature to separate gems (#258), until this is finished, you can use by locking the listen gem to version '~> 2.10'.
  • Some filesystems won't work without polling (VM/Vagrant Shared folders, NFS, Samba, sshfs, etc.).
  • Specs suite on JRuby and Rubinius aren't reliable on Travis CI, but should work.
  • Windows and *BSD adapter aren't continuously and automatically tested.
  • OSX adapter has some performance limitations (#342).
  • Ruby < 2.2.x is no longer supported - upgrade to Ruby 2.2 or 2.3.
  • Listeners do not notify across forked processes, if you wish for multiple processes to receive change notifications you must listen inside of each process.

Pull requests or help is very welcome for these.


The simplest way to install Listen is to use Bundler.

gem 'listen', '~> 3.0' # NOTE: for TCP functionality, use '~> 2.10' for now


Call with either a single directory or multiple directories, then define the "changes" callback in a block.

listener ='dir/to/listen', 'dir/to/listen2') do |modified, added, removed|
  puts "modified absolute path: #{modified}"
  puts "added absolute path: #{added}"
  puts "removed absolute path: #{removed}"
listener.start # not blocking

Pause / unpause / stop

Listeners can also be easily paused/unpaused:

listener ='dir/path/to/listen') { |modified, added, removed| puts 'handle changes here...' }

listener.paused? # => false
listener.processing? # => true

listener.pause   # stops processing changes (but keeps on collecting them)
listener.paused? # => true
listener.processing? # => false

listener.unpause # resumes processing changes ("start" would do the same)
listener.stop    # stop both listening to changes and processing them

Note: While paused, Listen keeps on collecting changes in the background - to clear them, call "stop"

Note: You should keep track of all started listeners and stop them properly on finish.

Ignore / ignore!

Listen ignores some directories and extensions by default (See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer), you can add ignoring patterns with the ignore option/method or overwrite default with ignore! option/method.

listener ='dir/path/to/listen', ignore: /\.txt/) { |modified, added, removed| # ... }
listener.ignore! /\.pkg/ # overwrite all patterns and only ignore pkg extension.
listener.ignore /\.rb/   # ignore rb extension in addition of pkg.

Note: :ignore regexp patterns are evaluated against relative paths.

Note: Ignoring paths does not improve performance, except when Polling (#274)


Listen catches all files (less the ignored ones) by default. If you want to only listen to a specific type of file (i.e., just .rb extension), you should use the only option/method.

listener ='dir/path/to/listen', only: /\.rb$/) { |modified, added, removed| # ... }
listener.only /_spec\.rb$/ # overwrite all existing only patterns.

Note: :only regexp patterns are evaluated only against relative file paths.

Changes callback

Changes to the listened-to directories gets reported back to the user in a callback. The registered callback gets invoked, when there are changes, with three parameters: modified, added and removed paths, in that particular order. Paths are always returned in their absolute form.


listener ='path/to/app') do |modified, added, removed|
  # This block will be called when there are changes.

or ...

# Create a callback
callback = do |modified, added, removed|
  # This proc will be called when there are changes.
listener ='dir', &callback)


All the following options can be set through the after the directory path(s) params.

ignore: [%r{/foo/bar}, /\.pid$/, /\.coffee$/]   # Ignore a list of paths
                                                # default: See DEFAULT_IGNORED_DIRECTORIES and DEFAULT_IGNORED_EXTENSIONS in Listen::Silencer

ignore!: %r{/foo/bar}                           # Same as ignore options, but overwrite default ignored paths.

only: %r{.rb$}                                  # Only listen to specific files
                                                # default: none

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

wait_for_delay: 4                               # Set the delay (**in seconds**) between calls to the callback when changes exist
                                                # default: 0.10 sec

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

relative: false                                 # Whether changes should be relative to current dir or not
                                                # default: false

polling_fallback_message: 'custom message'      # Set a custom polling fallback message (or disable it with false)
                                                # default: "Listen will be polling for changes. Learn more at"


Setting the environment variable LISTEN_GEM_DEBUGGING=1 sets up the INFO level logger, while LISTEN_GEM_DEBUGGING=2 sets up the DEBUG level logger.

You can also set Listen.logger to a custom logger.

Listen adapters

The Listen gem has a set of adapters to notify it when there are changes.

There are 4 OS-specific adapters to support Darwin, Linux, *BSD and Windows. These adapters are fast as they use some system-calls to implement the notifying function.

There is also a polling adapter - although it's much slower than other adapters, it works on every platform/system and scenario (including network filesystems such as VM shared folders).

The Darwin and Linux adapters are dependencies of the Listen gem so they work out of the box. For other adapters a specific gem will have to be added to your Gemfile, please read below.

The Listen gem will choose the best adapter automatically, if present. If you want to force the use of the polling adapter, use the :force_polling option while initializing the listener.

On Windows

If you are on Windows, it's recommended to use the wdm adapter instead of polling.

Please add the following to your Gemfile:

gem 'wdm', '>= 0.1.0' if Gem.win_platform?


If you are on *BSD you can try to use the rb-kqueue adapter instead of polling.

Please add the following to your Gemfile:

require 'rbconfig'
if RbConfig::CONFIG['target_os'] =~ /bsd|dragonfly/i
  gem 'rb-kqueue', '>= 0.2'

Getting the polling fallback message?

Please visit the installation section of the Listen WIKI for more information and options for potential fixes.

Issues and troubleshooting

NOTE: without providing the output after setting the LISTEN_GEM_DEBUGGING=1 environment variable, it can be almost impossible to guess why listen is not working as expected.



If Listen seems slow or unresponsive, make sure you're not using the Polling adapter (you should see a warning upon startup if you are).

Also, if the directories you're watching contain many files, make sure you're:

  • not using Polling (ideally)
  • using :ignore and :only options to avoid tracking directories you don't care about (important with Polling and on MacOS)
  • running Listen with the :latency and :wait_for_delay options not too small or too big (depends on needs)
  • not watching directories with log files, database files or other frequently changing files
  • not using a version of Listen prior to 2.7.7
  • not getting silent crashes within Listen (see LISTEN_GEM_DEBUGGING=2)
  • not running multiple instances of Listen in the background
  • using a file system with atime modification disabled (ideally)
  • not using a filesystem with inaccurate file modification times (ideally), e.g. HFS, VFAT
  • not buffering to a slow terminal (e.g. transparency + fancy font + slow gfx card + lots of output)
  • ideally not running a slow encryption stack, e.g. btrfs + ecryptfs

When in doubt, LISTEN_GEM_DEBUGGING=2 can help discover the actual events and time they happened.

See also Tips and Techniques.


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 must pass on Travis CI.
  • Update the Yard documentation.
  • Update the README.
  • Please do not change the version number.

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



  • You must have commit rights to the GitHub repository.
  • You must have push rights for

How to release

  1. Run bundle install to make sure that you have all the gems necessary for testing and releasing.
  2. Ensure all tests are passing by running bundle exec rake.
  3. Determine which would be the correct next version number according to semver.
  4. Update the version in ./lib/listen/version.rb.
  5. Update the version in the Install section of ./ (gem 'listen', '~> X.Y').
  6. Commit the version in a single commit, the message should be "Preparing vX.Y.Z"
  7. Run bundle exec rake release:full; this will tag, push to GitHub, and publish to
  8. Update and publish the release notes on the GitHub releases page if necessary



Thibaud Guillaume-Gentil (@thibaudgg)


You can’t perform that action at this time.