watchfiles

Simple, modern, and fast file watching and code-reload for Python, powered by a Rust core built on the `notify` crate

Library
PyPI
v1.3.0
2,560 stars
MIT License

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
72 /100 Good
Development Activity 72
Maintenance 60
Community 56
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
73 /100 Good
Architecture 75
Code Quality 78
Innovation 68
Learning Curve 70

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.

Used by 7 apps in this directory

Python
100%
Apache 2.0

Agno

AI Development · Automation · Devops

43,086

Build, run, and manage agent platforms with a full production stack — SDK, runtime, and control plane included.

View details
93
Repo Health
87
Technical
66
Dependency
Built with
Python 100%
Updated 1 weeks ago
TypeScript
84%
MIT

/dev/push

Developer Tools · Devops

4,822

Self-hosted, open-source Vercel alternative that deploys Python, Node.js, PHP, and any Docker-compatible app from a Git push, with zero-downtime rollouts and real-time logs.

View details
81
Repo Health
68
Technical
73
Dependency
Built with
TypeScript 84%
Updated 1 weeks ago
Python
57%
Apache 2.0

MLflow

AI Development · Monitoring

28,707

The open source AI engineering platform for debugging, evaluating, monitoring, and optimizing production LLMs and agents at scale.

View details
96
Repo Health
86
Technical
67
Dependency
Built with
Python 57%
TypeScript 36%
Updated 1 weeks ago
Python
72%
AGPL 3.0

OpenMontage

AI Agents · Video Editors

77,769

Open-source agentic video production system: your AI coding assistant researches, scripts, generates, edits and renders finished videos through approval-gated pipelines with budget controls.

View details
73
Repo Health
87
Technical
76
Dependency
Built with
Python 72%
HTML 18%
Updated 1 weeks ago
Python
63%
GPL 3.0

Paperless-ngx

Bookmarks Archiving

47,787

Turn your paper pile into a searchable digital archive with OCR, AI classification, and automated workflows — all running on your own server.

View details
91
Repo Health
88
Technical
67
Dependency
Built with
Python 63%
TypeScript 28%
Updated 1 weeks ago
Go
66%
MIT

sandboxd

Developer Tools · Devops

979

Self-hosted engine for AI app-builder products: give every user an isolated sandbox, a built-in coding agent, and a live preview URL — one command, no Kubernetes.

View details
78
Repo Health
83
Technical
68
Dependency
Built with
Go 66%
TypeScript 21%
Updated 1 weeks ago
TypeScript
66%
MIT

Scalar

Developer Tools

16,380

Beautiful, interactive OpenAPI documentation with a built-in offline-first API client and multi-language code generation — all in one open-source platform.

View details
90
Repo Health
89
Technical
65
Dependency
Built with
TypeScript 66%
Vue 28%
Updated 1 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers