Cross-platform filesystem notifications for Go.
fsnotify is a Go library to provide cross-platform filesystem notifications on Windows, Linux, macOS, BSD, and illumos.
Go 1.23 or newer is required; the full documentation is at https://pkg.go.dev/github.com/fsnotify/fsnotify
Platform support:
| Backend | OS | Status |
|---|---|---|
| inotify | Linux | Supported |
| kqueue | BSD, macOS | Supported |
| ReadDirectoryChangesW | Windows | Supported |
| FEN | illumos | Supported |
| fanotify | Linux 5.9+ | Not yet |
| FSEvents | macOS | Needs support in x/sys/unix |
| USN Journals | Windows | Needs support in x/sys/windows |
| Polling | All | Not yet |
Linux and illumos should include Android and Solaris, but these are currently untested.
A basic example:
…
Some more examples can be found in cmd/fsnotify, which can be run with:
% go run ./cmd/fsnotify
Further detailed documentation can be found in godoc: https://pkg.go.dev/github.com/fsnotify/fsnotify
No, not unless you are watching the location it was moved to.
No, you must add watches for any directory you want to watch (a recursive watcher is on the roadmap: #18).
fsnotify requires support from underlying OS to work. The current NFS and SMB protocols does not provide network level support for file notifications, and neither do the /proc and /sys virtual filesystems.
This could be fixed with a polling watcher (#9), but it's not yet implemented.
Some programs may generate a lot of attribute changes; for example Spotlight on macOS, anti-virus programs, backup applications, and some others are known to do this. As a rule, it's typically best to ignore Chmod events. They're often not useful, and tend to cause problems.
Spotlight indexing on macOS can result in multiple events (see #15). A temporary workaround is to add your folder(s) to the Spotlight Privacy settings until we have a native FSEvents implementation (see #11).
Watching individual files (rather than directories) is generally not recommended as many programs (especially editors) update files atomically: it will write to a temporary file which is then moved to a destination, overwriting the original (or some variant thereof). The watcher on the original file is now lost, as that no longer exists.
The upshot of this is that a power failure or crash won't leave a half-written file.
Watch the parent directory and use Event.Name to filter out files you're not
interested in. There is an example of this in cmd/fsnotify/file.go.
When a file is removed a REMOVE event won't be emitted until all file descriptors are closed; it will emit a CHMOD instead:
fp := os.Open("file")
os.Remove("file") // CHMOD
fp.Close() // REMOVE
This is the event that inotify sends, so not much can be changed about this.
The fs.inotify.max_user_watches sysctl variable specifies the upper limit for
the number of watches per user, and fs.inotify.max_user_instances specifies
the maximum number of inotify instances per user. Every Watcher you create is an
"instance", and every path you add is a "watch". Reaching the limit will result
in a "no space left on device" or "too many open files" error.
These are also exposed in /proc as /proc/sys/fs/inotify/max_user_watches and
/proc/sys/fs/inotify/max_user_instances. The default values differ per distro
and available memory.
To increase them you can use sysctl or write the value to proc file:
sysctl fs.inotify.max_user_watches=200000
sysctl fs.inotify.max_user_instances=256
To make the changes persist on reboot edit /etc/sysctl.conf or
/usr/lib/sysctl.d/50-default.conf (details differ per Linux distro; check your
distro's documentation):
fs.inotify.max_user_watches=200000
fs.inotify.max_user_instances=256
kqueue requires opening a file descriptor for every file that's being watched; so if you're watching a directory with five files then that's six file descriptors. You will run in to your system's "max open files" limit faster on these platforms.
The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to
control the maximum number of open files.
No open issues yet, or sync has not completed.