Watchdog

Warnings

• breaking Python 3.8 support was dropped in Watchdog v5.0.0. Python 3.7 support was dropped in v4.0.0. Ensure your Python environment is 3.9 or newer.
  Fix: Upgrade your Python interpreter to version 3.9 or later.
• breaking In v5.0.0, several core classes and exceptions were renamed (e.g., `BaseObserverSubclassCallable` to `ObserverType`, `UnsupportedLibc` to `UnsupportedLibcError`). Keyword arguments are now enforced in core API calls. `InotifyConstants.IN_CLOSE` was also removed.
  Fix: Update class/exception names and ensure keyword arguments are used for API calls.
• breaking In v6.0.0, the `inotify` backend now uses `select.poll()` instead of the deprecated `select.select()`, if available. Additionally, several unused functions from the `watchdog.utils.echo` module were removed.
  Fix: 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.
• gotcha Text editors like Vim often write to temporary files and then swap them in to replace the original, which may not trigger `on_modified` events.
  Fix: 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.
• gotcha On BSD/macOS systems using `kqueue`, Watchdog opens file descriptors for monitored items. Hitting the operating system's maximum open file descriptor limit can prevent Watchdog from monitoring new files or directories.
  Fix: 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.
• gotcha On Windows, the `ReadDirectoryChangesW` API has limitations: rename/movement events for directories may be reported before I/O is complete, and delete events for directories might be reported as file deletion events.
  Fix: 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.

Install

• pip install watchdog Install core library
• pip install 'watchdog[watchmedo]' Install with watchmedo utility

Imports

• Observer

  from watchdog.observers import Observer

• FileSystemEventHandler

  from watchdog.events import FileSystemEventHandler

• LoggingEventHandler

  from watchdog.events import LoggingEventHandler

  A built-in event handler for simple logging.

Quickstart

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.

import time
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler

class MyEventHandler(FileSystemEventHandler):
    def on_any_event(self, event):
        # Log any event for demonstration
        print(f"Event type: {event.event_type} | Path: {event.src_path} | Is directory: {event.is_directory}")

if __name__ == "__main__":
    path_to_watch = "."
    event_handler = MyEventHandler()
    observer = Observer()
    observer.schedule(event_handler, path_to_watch, recursive=True)
    observer.start()
    try:
        print(f"Monitoring directory: {path_to_watch}")
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        observer.stop()
    observer.join()