Install & Compatibility
Where this runs
tested against v1.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.236s · 21.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.206s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
watch
✓ from watchfiles import watch
Correct import path for the 'watch' function.
awatch
✓ from watchfiles import awatch
Correct import path for the 'awatch' function.
run_process
✓ from watchfiles import run_process
Correct import path for the 'run_process' function.
arun_process
✓ from watchfiles import arun_process
Correct import path for the 'arun_process' function.
A simple script to monitor changes in a directory using the 'watch' function from watchfiles.
from watchfiles import watch
for changes in watch('./path/to/dir'):
print(changes)
watchfiles --version
Debug
Known issues
breakingThe package was previously named 'watchgod'.fixRename imports from 'watchgod' to 'watchfiles'.
affects: All versions prior to 0.24.0
deprecatedPython 3.8 support was dropped in version 0.24.0.fixUpgrade to Python 3.9 or later.
affects: 0.24.0 and later
gotchaEnsure that the 'notify' Rust library is installed for optimal performance.fixInstall the 'notify' Rust library as per the installation instructions.
affects: All versions
gotchaThe `watch()` function expects a valid, existing file or directory path. Providing a non-existent path will result in a `FileNotFoundError`.fixEnsure that the path passed to `watch()` exists and is accessible at runtime. You may need to create the directory/file or adjust the path.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'watchfiles'
The 'watchfiles' package is not installed in the current Python environment.
fixpip install watchfiles
ImportError: cannot import name 'run_process' from 'watchfiles'
The 'run_process' function is not directly exposed from the top-level 'watchfiles' module for public use; the primary public function for running a watcher is 'watchfiles.run', which also supports running a target function in a separate process.
fixUse 'from watchfiles import run' and pass your target function via the 'target' argument, or use the 'watchfiles' CLI command directly.
TypeError: run() got an unexpected keyword argument 'target'
The 'paths' argument(s) for the 'watchfiles.run' function must be passed positionally, not as a keyword argument named 'target'. 'target' is used to specify the function to run in a separate process.
fixPass the path(s) as positional arguments, for example: 'watchfiles.run('.', target=my_function)'. TypeError: my_callback() takes 0 positional arguments but 1 was given
The callback function provided to 'watchfiles.run' must accept one argument, which will be a set of 'Change' tuples representing the detected file changes.
fixUpdate your callback function signature to accept one argument, for example: 'def my_callback(changes: set):\n for change, path in changes:\n print(f'{change.name}: {path}')' Upgrade
Version history
1.2.0latest on PyPI · released May 18, 2026
Audit
Dependencies
notifyrequiredProvides underlying file system notifications via the Notify Rust library.