# Watchdog — Python Library for Filesystem Event Monitoring

> Watchdog is a Python library and set of shell utilities for monitoring filesystem events, enabling applications to react to file changes, creations, and deletions in real time.

## Install

Save as a script file and run:

# Watchdog — Python Library for Filesystem Event Monitoring

## Quick Use
```bash
pip install watchdog
watchmedo log --recursive .
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-3a0e504d
Author: Script Depot