watchfiles

1.1.1 verified Tue May 12 auth: no python install: verified quickstart: stale

A simple, modern, and high-performance file watching and code reloading library for Python, currently at version 1.1.1, with a release cadence of approximately every 3-4 months.

pip install watchfiles

Common errors

error ModuleNotFoundError: No module named 'watchfiles' ↓

cause The 'watchfiles' package is not installed in the current Python environment.

fix

pip install watchfiles

error ImportError: cannot import name 'run_process' from 'watchfiles' ↓

cause 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.

fix

Use 'from watchfiles import run' and pass your target function via the 'target' argument, or use the 'watchfiles' CLI command directly.

error TypeError: run() got an unexpected keyword argument 'target' ↓

cause 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.

fix

Pass the path(s) as positional arguments, for example: 'watchfiles.run('.', target=my_function)'.

error TypeError: my_callback() takes 0 positional arguments but 1 was given ↓

cause The callback function provided to 'watchfiles.run' must accept one argument, which will be a set of 'Change' tuples representing the detected file changes.

fix

Update 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}')'

Warnings

breaking The package was previously named 'watchgod'. ↓

fix Rename imports from 'watchgod' to 'watchfiles'.

deprecated Python 3.8 support was dropped in version 0.24.0. ↓

fix Upgrade to Python 3.9 or later.

gotcha Ensure that the 'notify' Rust library is installed for optimal performance. ↓

fix Install the 'notify' Rust library as per the installation instructions.

gotcha The `watch()` function expects a valid, existing file or directory path. Providing a non-existent path will result in a `FileNotFoundError`. ↓

fix Ensure that the path passed to `watch()` exists and is accessible at runtime. You may need to create the directory/file or adjust the path.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.20s 21.7M

3.10 slim (glibc) - - 0.15s 22M

3.11 alpine (musl) - - 0.33s 23.6M

3.11 slim (glibc) - - 0.27s 24M

3.12 alpine (musl) - - 0.55s 15.4M

3.12 slim (glibc) - - 0.54s 16M

3.13 alpine (musl) - - 0.25s 14.7M

3.13 slim (glibc) - - 0.23s 15M

3.9 alpine (musl) - - 0.21s 21.0M

3.9 slim (glibc) - - 0.17s 21M

Imports

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.

Quickstart stale last tested: 2026-04-23

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)