notify-rs/notify

Notify is a cross-platform filesystem notification library for Rust. It provides a unified interface for monitoring filesystem events across different operating systems.

Supported Platforms and Mechanisms:

• Linux / Android: inotify
• macOS: FSEvents or kqueue (depending on features)
• Windows: ReadDirectoryChangesW
• iOS / FreeBSD / NetBSD / OpenBSD / DragonflyBSD: kqueue
• All platforms: polling (fallback mechanism)

Note: If you are looking for desktop notifications (system alerts) rather than filesystem event monitoring, use notify-rust or alert-after instead.

Notify Debouncer Full is a debouncer for the notify crate designed for ease of use. It reduces event noise by performing the following logic:

• Rename Matching: Emits a single Rename event only if the From and To events can be matched. It merges multiple Rename events and updates paths for pending events that occurred before the rename.
• File ID Tracking: Optionally uses file system IDs (supported on FSevents and Windows) to stitch rename events together.
• Duplicate Suppression:
  • Emits only one Remove event when deleting a directory (on inotify).
  • Prevents duplicate Create events.
  • Prevents Modify events from being emitted immediately after a Create event.

The current Minimum Supported Rust Version (MSRV) for notify is 1.88.

Project policy guarantees support for the current stable Rust release and the previous two stable releases (N, N-1, N-2).

In notify v9, calling Watcher::watch on a path that is already being watched will replace the existing watch with the new configuration (recursive mode and reported path) upon success. It does not create a second independent watch. To remove the watch, a single Watcher::unwatch call is used.

watcher.watch(path, notify::RecursiveMode::Recursive)?;
watcher.watch(path, notify::RecursiveMode::NonRecursive)?;

// `path` is now watched non-recursively.
watcher.unwatch(path)?;

In notify v9, the PathsMut type and Watcher::paths_mut() method were removed. They are replaced by Watcher::update_paths(Vec<PathOp>).

To update multiple paths, create a vector of PathOp operations (such as PathOp::watch_recursive) and pass them to update_paths. This method applies operations in order and stops on the first error. If it fails, it returns an UpdatePathsError which contains the source error, the origin of the failure, and the remaining operations that were not attempted, allowing for retry logic.

use notify::{PathOp, Result, Watcher};

fn add_many_paths<W: Watcher>(watcher: &mut W, paths: &[std::path::PathBuf]) -> Result<()> {
    let ops = paths
        .iter()
        .cloned()
        .map(PathOp::watch_recursive)
        .collect::<Vec<_>>();

    watcher.update_paths(ops).map_err(notify::Error::from)?;
    Ok(())
}

The notify-debouncer-full crate provides advanced debouncing capabilities:

• monitor_debounced: A basic usage example for standard debouncing.
• debouncer_full: An advanced example demonstrating how to access the internal file ID cache.

The notify-debouncer-mini crate provides lightweight debouncing options:

• debouncer_mini: A basic usage example for the mini debouncer.
• debouncer_mini_custom: Demonstrates how to use the mini debouncer with a specific backend, such as PollWatcher.

In notify v5, the library only provides precise events. The RawEvent type from v4 has been replaced by Event.

If your application requires debouncing, you must now use the separate notify-debouncer-mini crate. The old DebouncedEvent type has been removed. The new notify-debouncer-mini crate reports an Any-like event (also named DebouncedEvent), but it is recommended to verify the actual file state rather than relying solely on the event kind, as event behavior is highly platform-specific.

In notify v9, Event.paths and Watcher::watched_paths() use the same root representation passed to Watcher::watch or Watcher::update_paths.

If you watch a relative path like src, events will report relative paths like src/lib.rs. If you require absolute paths, you must convert the path to an absolute path before calling watch or update_paths.

let path = std::env::current_dir()?.join("src");
watcher.watch(&path, notify::RecursiveMode::Recursive)?;

Internal Channels

notify v5 uses crossbeam-channel by default. If you are using tokio and encounter compatibility issues, you may need to disable this feature.

macOS Backend

For macOS, you can choose between the default fsevent backend or the kqueue backend by enabling the macos_kqueue feature.