Watchdog is a Python library and shell utility that provides an API for monitoring file system events in real-time. It supports various operating systems by utilizing native APIs like inotify (Linux), FSEvents (macOS), and ReadDirectoryChangesW (Windows), falling back to polling when native APIs are unavailable. Currently at version 6.0.0, the library maintains an active development pace with major releases approximately annually.
pip install watchdogVerified import paths — ran on the pinned version, not inferred.
This quickstart monitors the current directory ('.') recursively for any filesystem events using a custom event handler and prints them to the console. The observer runs in a separate thread until a KeyboardInterrupt is received.
Upgrade your Python interpreter to version 3.9 or later.
Update class/exception names and ensure keyword arguments are used for API calls.
Update any custom `inotify` implementations to reflect `select.poll()` usage if directly interacting with low-level components. Remove any calls to the deprecated `echo` module functions.
Configure your editor to disable features that involve backup files or temporary swaps, or consider monitoring the parent directory for `on_moved` events if file replacement is the expected pattern.
Increase the per-process file descriptor limit on your operating system (`ulimit -n` on Unix-like systems) or adjust your monitoring strategy to cover fewer paths if possible.
Implement robust error handling and potentially introduce small delays when processing Windows-specific move/delete events to account for eventual consistency, and be prepared to infer directory deletions from file deletion events.
Ensure that the directory or file path passed to `observer.schedule()` exists before starting the observer. Verify permissions if the path exists but is inaccessible, as this can also lead to similar errors.
Verify that the directory or file path you are attempting to monitor exists and is accessible before calling `observer.start()` or scheduling the watch. This error often suggests a typo in the path argument or that the target filesystem item was deleted unexpectedly.
pip install watchdog
from watchdog.observers import Observer
Increase the `fs.inotify.max_user_watches` kernel parameter, e.g., by running `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf; sudo sysctl -p`
Ensure `observer.start()` is called before `observer.stop()` and `observer.join()`, and avoid calling `stop()` or `join()` multiple times on the same observer instance.