Repository files navigation

Minimal and efficient cross-platform file watching library

There are many reasons to prefer Chokidar to raw fs.watch / fs.watchFile in 2026:

• Events are properly reported
  • macOS events report filenames
  • events are not reported twice
  • changes are reported as add / change / unlink instead of uselessrename
• Atomic writes are supported, usingatomic option
  • Some file editors use them
• Chunked writes are supported, usingawaitWriteFinish option
  • Large files are commonly written in chunks
• File / dir filtering is supported
• Symbolic links are supported
• Recursive watching is always supported, instead of partial when using raw events
  • Includes a way to limit recursion depth

Chokidar relies on the Node.js corefs module, but when usingfs.watch andfs.watchFile for watching, it normalizes the events itreceives, often checking for truth by getting file stats and/or dir contents.Thefs.watch-based implementation is the default, whichavoids polling and keeps CPU usage down. Be advised that chokidar will initiatewatchers recursively for everything within scope of the paths that have beenspecified, so be judicious about not wasting system resources by watching muchmore than needed. For some cases,fs.watchFile, which utilizes polling and uses more resources, is used.

Made forBrunch in 2012,it is now used in~30 million repositories andhas proven itself in production environments.

• Nov 2025 update: v5 is out. Makes package ESM-only and increases minimum node.js requirement to v20.
• Sep 2024 update: v4 is out! It decreases dependency count from 13 to 1, removessupport for globs, adds support for ESM / Common.js modules, and bumps minimum node.js version from v8 to v14.Check outupgrading.

Install with npm:

npm install chokidar

Use it in your code:

importchokidarfrom'chokidar';// One-liner for current directorychokidar.watch('.').on('all',(event,path)=>{console.log(event,path);});// Extended options// ----------------// Initialize watcher.constwatcher=chokidar.watch('file, dir, or array',{ignored:(path,stats)=>stats?.isFile()&&!path.endsWith('.js'),// only watch js filespersistent:true,});// Something to use when events are received.constlog=console.log.bind(console);// Add event listeners.watcher.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.watcher.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)=>{// internallog('Raw event info:',event,path,details);});// 'add', 'addDir' and 'change' events also receive stat() results as second// argument when available: https://nodejs.org/api/fs.html#fs_class_fs_statswatcher.on('change',(path,stats)=>{if(stats)console.log(`File${path} changed size to${stats.size}`);});// Watch new files.watcher.add('new-file');watcher.add(['new-file-2','new-file-3']);// Get list of actual paths being watched on the filesystemletwatchedPaths=watcher.getWatched();// Un-watch some files.awaitwatcher.unwatch('new-file');// Stop watching. The method is async!awaitwatcher.close().then(()=>console.log('closed'));// Full list of options. See below for descriptions.// Do not use this example!chokidar.watch('file',{persistent:true,// ignore .txt filesignored:(file)=>file.endsWith('.txt'),// watch only .txt files// ignored: (file, _stats) => _stats?.isFile() && !file.endsWith('.txt'),awaitWriteFinish:true,// emit single event when chunked writes are completedatomic:true,// emit proper events when "atomic writes" (mv _tmp file) are used// The options also allow specifying custom intervals in ms// awaitWriteFinish: {//   stabilityThreshold: 2000,//   pollInterval: 100// },// atomic: 100,interval:100,binaryInterval:300,cwd:'.',depth:99,followSymlinks:true,ignoreInitial:false,ignorePermissionErrors:false,usePolling:false,alwaysStat:false,});

chokidar.watch(paths, [options])

• paths (string or array of strings). Paths to files, dirs to be watchedrecursively.
• options (object) Options object as defined below:

• persistent (default:true). Indicates whether the processshould continue to run as long as files are being watched.

• ignored function, regex, or path. Defines files/paths to be ignored.The whole relative or absolute path is tested, not just filename. If a function with two argumentsis provided, it gets called twice per path - once with a single argument (the path), secondtime with two arguments (the path and thefs.Statsobject of that path).
• ignoreInitial (default:false). If set tofalse thenadd/addDir events are also emitted for matching paths whileinstantiating the watching as chokidar discovers these file paths (before theready event).
• followSymlinks (default:true). Whenfalse, only thesymlinks themselves will be watched for changes instead of followingthe link references and bubbling events through the link's path.
• cwd (no default). The base directory from which watchpaths are to bederived. Paths emitted with events will be relative to this.

• usePolling (default:false).Whether to use fs.watchFile (backed by polling), or fs.watch. If pollingleads to high CPU utilization, consider setting this tofalse. It istypically necessary toset this totrue to successfully watch files overa network, and it may be necessary to successfully watch files in othernon-standard situations. Setting totrue explicitly on MacOS overrides theuseFsEvents default. You may also set the CHOKIDAR_USEPOLLING env variableto true (1) or false (0) in order to override this option.
• Polling-specific settings (effective whenusePolling: true)
  • interval (default:100). Interval of file system polling, in milliseconds. You may alsoset the CHOKIDAR_INTERVAL env variable to override this option.
  • binaryInterval (default:300). Interval of file systempolling for binary files.(see list of binary extensions)
• alwaysStat (default:false). If relying upon thefs.Statsobject that may get passed withadd,addDir, andchange events, setthis totrue to ensure it is provided even in cases where it wasn'talready available from the underlying watch events.
• depth (default:undefined). If set, limits how many levels ofsubdirectories will be traversed.
• awaitWriteFinish (default:false).By default, theadd event will fire when a file first appears on disk, beforethe entire file has been written. Furthermore, in some cases somechangeevents will be emitted while the file is being written. In some cases,especially when watching for large files there will be a need to wait for thewrite operation to finish before responding to a file creation or modification.SettingawaitWriteFinish totrue (or a truthy value) will poll file size,holding itsadd andchange events until the size does not change for aconfigurable amount of time. The appropriate duration setting is heavilydependent on the OS and hardware. For accurate detection this parameter shouldbe relatively high, making file watching much less responsive.Use with caution.
  • options.awaitWriteFinish can be set to an object in order to adjusttiming params:
  • awaitWriteFinish.stabilityThreshold (default: 2000). Amount of time inmilliseconds for a file size to remain constant before emitting its event.
  • awaitWriteFinish.pollInterval (default: 100). File size polling interval, in milliseconds.

• ignorePermissionErrors (default:false). Indicates whether to watch filesthat don't have read permissions if possible. If watching fails due toEPERMorEACCES with this set totrue, the errors will be suppressed silently.
• atomic (default:true ifuseFsEvents andusePolling arefalse).Automatically filters out artifacts that occur when using editors that use"atomic writes" instead of writing directly to the source file. If a file isre-added within 100 ms of being deleted, Chokidar emits achange eventrather thanunlink thenadd. If the default of 100 ms does not work wellfor you, you can override it by settingatomic to a custom value, inmilliseconds.

chokidar.watch() produces an instance ofFSWatcher. Methods ofFSWatcher:

• .add(path / paths): Add files, directories for tracking.Takes an array of strings or just one string.
• .on(event, callback): Listen for an FS event.Available events:add,addDir,change,unlink,unlinkDir,ready,raw,error.Additionallyall is available which gets emitted with the underlying eventname and path for every event other thanready,raw, anderror.raw is internal, use it carefully.
• .unwatch(path / paths): Stop watching files or directories.Takes an array of strings or just one string.
• .close():async Removes all listeners from watched files. Asynchronous, returns Promise. Use withawait to ensure bugs don't happen.
• .getWatched(): Returns an object representing all the paths on the filesystem being watched by thisFSWatcher instance. The object's keys are all thedirectories (using absolute paths unless thecwd option was used), and thevalues are arrays of the names of the items contained in each directory.

Check out third partychokidar-cli,which allows to execute a command on each change, or get a stdio stream of change events.

Sometimes, Chokidar runs out of file handles, causingEMFILE andENOSP errors:

• bash: cannot set terminal process group (-1): Inappropriate ioctl for device bash: no job control in this shell
• Error: watch /home/ ENOSPC

There are two things that can cause it.

1. Exhausted file handles for generic fs operations
   • Can be solved by usinggraceful-fs,which can monkey-patch nativefs module used by chokidar:let fs = require('fs'); let grfs = require('graceful-fs'); grfs.gracefulify(fs);
   • Can also be solved by tuning OS:echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p.
2. Exhausted file handles forfs.watch
   • Can't seem to be solved by graceful-fs or OS tuning
   • It's possible to start usingusePolling: true, which will switch backend to resource-intensivefs.watchFile

All fsevents-related issues (WARN optional dep failed,fsevents is not a constructor) are solved by upgrading to v4+.

• v4 (Sep 2024): remove glob support and bundled fsevents. Decrease dependency count from 13 to 1. Rewrite in typescript. Bumps minimum node.js requirement to v14+
• v3 (Apr 2019): massive CPU & RAM consumption improvements; reduces deps / package size by a factor of 17x and bumps Node.js requirement to v8.16+.
• v2 (Dec 2017): globs are now posix-style-only. Tons of bugfixes.
• v1 (Apr 2015): glob support, symlink support, tons of bugfixes. Node 0.8+ is supported
• v0.1 (Apr 2012): Initial release, extracted fromBrunch

If you've used globs before and want do replicate the functionality with v4:

// v3chok.watch('**/*.js');chok.watch('./directory/**/*');// v4chok.watch('.',{ignored:(path,stats)=>stats?.isFile()&&!path.endsWith('.js'),// only watch js files});chok.watch('./directory');// other wayimport{glob}from'node:fs/promises';constwatcher=watch(awaitArray.fromAsync(glob('**/*.js')));// unwatching// v3chok.unwatch('**/*.js');// v4chok.unwatch(awaitArray.fromAsync(glob('**/*.js')));

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). This word is also used in other languages like Urdu as (چوکیدار) which is widely used in Pakistan and India.

MIT (c) Paul Miller (https://paulmillr.com), seeLICENSE file.