Watchdog — Python Library for Filesystem Event Monitoring

Introduction

Watchdog provides a Python API and command-line utilities to monitor filesystem events. It uses platform-native backends (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) for efficient, low-latency change detection.

What Watchdog Does

• Monitors directories for file creation, modification, deletion, and move events
• Uses native OS APIs for efficient event delivery without polling
• Provides the watchmedo CLI for running shell commands or logging on file changes
• Supports recursive directory watching with configurable event filtering
• Offers both synchronous and threaded observer patterns for flexible integration

Architecture Overview

Watchdog's Observer class spawns a background thread that delegates to a platform-specific EventEmitter. On Linux, this uses inotify file descriptors; on macOS, the FSEvents C API; on Windows, ReadDirectoryChangesW. Events are dispatched to user-supplied FileSystemEventHandler subclasses. A polling fallback is available for network filesystems or unsupported platforms.

Self-Hosting & Configuration

• Install from PyPI with pip install watchdog (includes the watchmedo CLI)
• Instantiate an Observer, schedule a handler on a target path, then call observer.start()
• Use the PatternMatchingEventHandler to filter events by filename glob patterns
• Configure recursive watching by passing recursive=True to observer.schedule()
• The polling observer (PollingObserver) works on any filesystem but with higher latency

Key Features

• Cross-platform support for Linux (inotify), macOS (FSEvents), Windows (ReadDirectoryChangesW), and BSD (kqueue)
• Built-in watchmedo CLI with subcommands for logging, auto-restart, and shell-trick execution
• Pattern and ignore-pattern filtering to process only relevant file changes
• Thread-safe observer that integrates into existing applications without blocking
• Stable API maintained since 2010 with consistent backwards compatibility

Comparison with Similar Tools

• inotifywait — Linux-only CLI for inotify events; Watchdog is cross-platform with a Python API
• fswatch — C-based cross-platform file watcher; Watchdog integrates directly into Python applications
• chokidar — Node.js file watcher; Watchdog is the Python ecosystem equivalent
• entr — CLI tool that runs commands on file changes; Watchdog provides programmatic event handling and filtering
• watchexec — Rust-based CLI for re-running commands; Watchdog is a library-first tool for Python codebases

FAQ

Q: Does Watchdog use polling by default? A: No. Watchdog uses native OS event APIs by default and only falls back to polling when explicitly configured or when native APIs are unavailable.

Q: Can I watch network-mounted filesystems? A: Native event APIs generally do not work on network mounts. Use PollingObserver for NFS, SMB, or other remote filesystems.

Q: How do I handle rapid successive events for the same file? A: Implement debouncing in your event handler using a timer or queue pattern, as Watchdog delivers raw OS-level events without built-in coalescing.

Q: Is Watchdog thread-safe? A: Yes. The Observer runs in its own thread and dispatches events to handlers in that thread. Use standard synchronization if your handler accesses shared state.

Sources

• https://github.com/gorakhargosh/watchdog
• https://python-watchdog.readthedocs.io/