watchfiles¶

Documentation for version: v1.0.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:

watch Usage

from watchfiles import watch

for changes in watch('./path/to/dir'):
    print(changes)

See watch 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.

awatch Usage

import asyncio
from watchfiles import awatch

async def main():
    async for changes in awatch('/path/to/dir'):
        print(changes)

asyncio.run(main())

See awatch docs for more details.

run_process Usage

from watchfiles import run_process

def foobar(a, b, c):
    ...

if __name__ == '__main__':
    run_process('./path/to/dir', target=foobar, args=(1, 2, 3))

See run_process docs for more details.

arun_process Usage

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())

See arun_process docs for more details.

Installation¶

watchfiles requires Python 3.8 to Python 3.13.

From PyPI¶

Using pip:

pip install watchfiles

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:

mamba install -c conda-forge watchfiles

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.