watchfiles

watchfiles gives Python applications efficient filesystem change notifications by wrapping Rust’s battle-tested notify crate, which itself uses native OS APIs (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows) instead of slow polling. It exposes both a simple synchronous watch() generator and an awatch() async generator built on anyio, plus a run_process() helper that restarts a subprocess whenever watched files change.

Created by Samuel Colvin (also known for pydantic), watchfiles is the file-watching engine behind uvicorn’s --reload flag and is widely used for development auto-reload tooling across the Python ecosystem, offering large performance gains over pure-Python polling-based watchers.

What You Get

• Synchronous watch() and async awatch() generators yielding sets of (Change, path) tuples
• A run_process() helper that restarts a target function or command whenever watched paths change
• A Rust-native core (_rust_notify) using OS-level inotify/FSEvents/ReadDirectoryChangesW instead of polling
• Built-in and composable filters (DefaultFilter, PythonFilter, .gitignore-aware filtering) to ignore noise like .git or __pycache__
• A watchfiles CLI entry point for watching and re-running arbitrary shell commands from the terminal

Common Use Cases

• Powering auto-reload in ASGI servers like uvicorn when source files change during development
• Triggering asset rebuilds or test re-runs on file save in developer tooling and build scripts
• Watching config or data directories in long-running services to hot-reload settings without a restart
• Driving custom dev-server or CLI watch-and-rerun workflows via the bundled run_process() helper

Under The Hood

Architecture The Python-facing layer (watchfiles/main.py, run.py, cli.py, filters.py) is a thin orchestration layer over a compiled Rust extension (src/lib.rs) that wraps the notify crate; main.py implements the watch/awatch generators with debounce/batching logic, run.py implements run_process() by combining watch() with subprocess management, and filters.py supplies composable path-filtering classes applied before events reach user code.

Tech Stack A hybrid Rust/Python project built with maturin as the PyO3 build backend; the Python side depends only on anyio>=3.0.0 for async support, targets Python 3.10+, and ships prebuilt wheels per platform so users never need a Rust toolchain to install it.

Code Quality The repository has a substantial test suite (test_watch.py, test_rust_notify.py, test_run_process.py, test_cli.py, test_filters.py, test_force_polling.py) covering the Rust/Python boundary, CLI, and filtering logic, plus py.typed for full type-checker support; code is organized into small, single-purpose modules with clear naming.

API Design The API surface is deliberately small and idiomatic — watch()/awatch() behave like standard Python/async generators requiring no special setup, run_process() covers the common reload-on-change pattern in one call, and documentation (mkdocs site plus in-repo docs/) walks through both basic and advanced filtering with runnable examples.