2.5k stars · MIT · 1.2.0 on PyPI (2026-05-18); for a Python tool the registry is believed over GitHub · Track this in Scout
It watches files and restarts your Python program the moment one of them changes, using the operating system's own notifications rather than polling.
▶Repo detailsthe review · specs · pros & cons · install
What it is
A Python library with a small command-line tool, written in Rust for speed. It uses the notification service the operating system already provides rather than repeatedly asking. It gives you a plain loop over changes, an asynchronous version, and a watchfiles command that restarts any command you give it.What it is good for. Any Python developer, and anyone whose project needs to react when a file lands in a folder. The problem it removes is the manual restart, and the battery cost of the naive way of avoiding it. A short line about Grasppy and ScalpingMate: both are Python, and the --reload option people already use in development is this library underneath.
- Almost no cost while nothing is happening, because it waits for the operating system to speak rather than asking it.
- It is already proven at scale: it is what several widely used development servers rely on.
- MIT licence, by the author of pydantic, and the published version is 1.2.0 of 18 May 2026 on PyPI.
- Watching files across a shared folder or a network drive does not work reliably. That is the operating system's limit, not this library's.
- On a very large folder tree the first scan is slow, so point it at the directory you care about rather than the whole project.
- It restarts a process. It does not swap code inside a running one, so anything held in memory is lost on each change.
- gorakhargosh/watchdog
The older and much broader Python file-watching library, with more features and noticeably more overhead.
Track this in Scout - watchexec/watchexec
A standalone command that runs anything when files change, with no Python involved at all.
Track this in Scout
source venv/bin/activate
pip install watchfiles
# Restart a command whenever anything in ./app changes:
watchfiles 'python -m myapp' app
# Or from inside Python:
# from watchfiles import watch
# for changes in watch('./app'):
# print(changes)