watchfiles¶
Documentation for version: v0.24.0.
Simple, modern and high performance file watching and code reload in python.
Underlying file system notifications are handled by the Notify rust library.
This package was previously named "watchgod", see Migrating from watchgod for more information.
Usage¶
Here are some examples of what watchfiles can do:
Seewatch
docs for more details.
watch
(and all other methods) can watch either files or directories and can watch more than one path with
a single instance.
import asyncio
from watchfiles import awatch
async def main():
async for changes in awatch('/path/to/dir'):
print(changes)
asyncio.run(main())
awatch
docs for more details.
from watchfiles import run_process
def foobar(a, b, c):
...
if __name__ == '__main__':
run_process('./path/to/dir', target=foobar, args=(1, 2, 3))
run_process
docs for more details.
import asyncio
from watchfiles import arun_process
def foobar(a, b, c):
...
async def main():
await arun_process('./path/to/dir', target=foobar, args=(1, 2, 3))
if __name__ == '__main__':
asyncio.run(main())
arun_process
docs for more details.
Installation¶
watchfiles requires Python 3.8 to Python 3.13.
From PyPI¶
Using pip
:
Binaries are available for:
- Linux:
x86_64
,aarch64
,i686
,armv7l
,musl-x86_64
&musl-aarch64
- MacOS:
x86_64
&arm64
(except python 3.7) - Windows:
amd64
&win32
From conda-forge¶
Using conda
or mamba
:
Binaries are available for:
- Linux:
x86_64
- MacOS:
x86_64
&arm64
(except python 3.7) - Windows:
amd64
From source¶
You can also install from source which requires Rust stable to be installed.
How Watchfiles Works¶
watchfiles is based on the Notify rust library.
All the hard work of integrating with the OS's file system events notifications and falling back to polling is palmed off onto the rust library.
"Debouncing" changes - e.g. grouping changes into batches rather than firing a yield/reload for each file changed is managed in rust.
The rust code takes care of creating a new thread to watch for file changes so in the case of the synchronous methods
(watch
and run_process
) no threading logic is required in python. When using the asynchronous methods (awatch
and
arun_process
) anyio.to_thread.run_sync
is used to wait for changes in a thread.