Chokidar Weekly downloads Yearly downloads

Minimal and efficient cross-platform file watching library




Node.js fs.watchFile:

Chokidar resolves these problems.

Initially made for Brunch (an ultra-swift web app build tool), it is now used in Microsoft’s Visual Studio Code, gulp, karma, PM2, browserify, webpack, BrowserSync, and many others. It has proven itself in production environments.

Version 3 is out! Check out our blog post about it: Chokidar 3: How to save 32TB of traffic every week


Chokidar does still rely on the Node.js core fs module, but when using and fs.watchFile for watching, it normalizes the events it receives, often checking for truth by getting file stats and/or dir contents.

On MacOS, chokidar by default uses a native extension exposing the Darwin FSEvents API. This provides very efficient recursive watching compared with implementations like kqueue available on most *nix platforms. Chokidar still does have to do some work to normalize the events received that way as well.

On most other platforms, the implementation is the default, which avoids polling and keeps CPU usage down. Be advised that chokidar will initiate watchers recursively for everything within scope of the paths that have been specified, so be judicious about not wasting system resources by watching much more than needed.

Getting started

Install with npm:

npm install chokidar

Then require and use it in your code:

const chokidar = require('chokidar');

// One-liner for current directory'.').on('all', (event, path) => {
  console.log(event, path);


// Example of a more typical implementation structure

// Initialize watcher.
const watcher ='file, dir, glob, or array', {
  ignored: /(^|[\/\\])\../, // ignore dotfiles
  persistent: true

// Something to use when events are received.
const log = console.log.bind(console);
// Add event listeners.
  .on('add', path => log(`File ${path} has been added`))
  .on('change', path => log(`File ${path} has been changed`))
  .on('unlink', path => log(`File ${path} has been removed`));

// More possible events.
  .on('addDir', path => log(`Directory ${path} has been added`))
  .on('unlinkDir', path => log(`Directory ${path} has been removed`))
  .on('error', error => log(`Watcher error: ${error}`))
  .on('ready', () => log('Initial scan complete. Ready for changes'))
  .on('raw', (event, path, details) => { // internal
    log('Raw event info:', event, path, details);

// 'add', 'addDir' and 'change' events also receive stat() results as second
// argument when available:
watcher.on('change', (path, stats) => {
  if (stats) console.log(`File ${path} changed size to ${stats.size}`);

// Watch new files.
watcher.add(['new-file-2', 'new-file-3', '**/other-file*']);

// Get list of actual paths being watched on the filesystem
var watchedPaths = watcher.getWatched();

// Un-watch some files.
await watcher.unwatch('new-file*');

// Stop watching.
// The method is async!
watcher.close().then(() => console.log('closed'));

// Full list of options. See below for descriptions.
// Do not use this example!'file', {
  persistent: true,

  ignored: '*.txt',
  ignoreInitial: false,
  followSymlinks: true,
  cwd: '.',
  disableGlobbing: false,

  usePolling: false,
  interval: 100,
  binaryInterval: 300,
  alwaysStat: false,
  depth: 99,
  awaitWriteFinish: {
    stabilityThreshold: 2000,
    pollInterval: 100

  ignorePermissionErrors: false,
  atomic: true // or a custom 'atomicity delay', in milliseconds (default 100)
});, [options])


Path filtering



Methods & Events produces an instance of FSWatcher. Methods of FSWatcher:


If you need a CLI interface for your file watching, check out chokidar-cli, allowing you to execute a command on each change, or get a stdio stream of change events.

Install Troubleshooting


For more detailed changelog, see


Why was chokidar named this way? What’s the meaning behind it?

Chowkidar is a transliteration of a Hindi word meaning ‘watchman, gatekeeper’, चौकीदार. This ultimately comes from Sanskrit _ चतुष्क_ (crossway, quadrangle, consisting-of-four).


MIT (c) Paul Miller (, see LICENSE file.