chokidar

# Chokidar [![Weekly downloads](https://img.shields.io/npm/dw/chokidar.svg)](https://github.com/paulmillr/chokidar)

Minimal and efficient cross-platform file watching library

## Why?

Raw `fs.watch` / `fs.watchFile` are useless: `fs.watch` reports many changes as an
non-transparent `rename`, can fire twice for one change, and recursive watching differs across
platforms. Chokidar normalizes all of that:

- Proper `add` / `change` / `unlink` (and `addDir` / `unlinkDir`) events, verified, deduplicated, with
  paths on every platform.
- Native `fs.watch` by default, which keeps CPU usage down; stat-based polling is available for
  network and other unusual filesystems.
- Recursive watching everywhere, with an optional depth limit, path filtering, and symlink support.
- Editor "atomic writes" (`atomic`) and chunked writes of large files (`awaitWriteFinish`) are
  handled.

Chokidar watches everything under the paths you give it, so scope them (and use `ignored` /
`depth`) rather than watching more than you need.

Made for [Brunch](https://brunch.io/) in 2012, it is now used in
[30+ million projects](https://www.npmjs.com/browse/depended/chokidar) and has proven itself
in production environments. The current major is [v6 (Oct 2026)](#changelog) - with lots of major improvements.

## Getting started

```sh
npm install chokidar
```

```js
import chokidar from 'chokidar';
// or: import { watch } from 'chokidar';
// or: const chokidar = require('chokidar');

chokidar.watch('src').on('all', (event, path) => console.log(event, path));
```

A fuller example:

```js
import chokidar from 'chokidar';

const watcher = chokidar.watch('src', {
  // strings are exact paths (not globs), regexes test the whole path, functions get (path, stats?)
  ignored: [
    /(^|\/)\../, // dotfiles
    (path, stats) => stats?.isFile() && !path.endsWith('.js'), // only .js files
  ],
  ignoreInitial: true, // don't emit add/addDir for files that already exist
});

watcher
  .on('add', (path, stats) => console.log('added', path, stats?.size))
  .on('change', (path) => console.log('changed', path))
  .on('unlink', (path) => console.log('removed', path))
  .on('ready', () => console.log('initial scan done'))
  .on('error', (err) => console.error(err));

watcher.add(['lib', 'index.js']); // add more paths later
watcher.unwatch('lib'); // synchronous
console.log(watcher.getWatched()); // { '/abs': ['src'], '/abs/src': ['a.js', 'sub'], ... }
await watcher.close(); // async and terminal: create a new watcher to resume
```

Recipes:

```js
// Large or chunked writes, and editors that save via temp file + rename
chokidar.watch('uploads', {
  awaitWriteFinish: { stabilityThreshold: 2000, pollInterval: 100 }, // wait for size to settle
  atomic: 100, // unlink + add within 100 ms becomes one change
});

// Network or otherwise unusual filesystems where fs.watch is unreliable
chokidar.watch('/mnt/nfs/data', { backend: 'polling', pollingInterval: 500 });
```

## API

`chokidar.watch(paths, [o