# watchfiles

> Simple, modern and high performance file watching and code reload in python.

- **URL**: https://www.freshcrate.ai/projects/watchfiles
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `v1.2.0` (2026-05-18)
- **License**: MIT
- **Source**: https://github.com/samuelcolvin/watchfiles/releases
- **Homepage**: https://github.com/samuelcolvin/watchfiles
- **Language**: Python
- **GitHub**: 2,463 stars, 133 forks
- **Registry**: pypi (`watchfiles`)
- **Tags**: `pypi`

## Description

# watchfiles

[![CI](https://github.com/samuelcolvin/watchfiles/actions/workflows/ci.yml/badge.svg)](https://github.com/samuelcolvin/watchfiles/actions/workflows/ci.yml?query=branch%3Amain)
[![Coverage](https://codecov.io/gh/samuelcolvin/watchfiles/branch/main/graph/badge.svg)](https://codecov.io/gh/samuelcolvin/watchfiles)
[![pypi](https://img.shields.io/pypi/v/watchfiles.svg)](https://pypi.python.org/pypi/watchfiles)
[![CondaForge](https://img.shields.io/conda/v/conda-forge/watchfiles.svg)](https://anaconda.org/conda-forge/watchfiles)
[![license](https://img.shields.io/github/license/samuelcolvin/watchfiles.svg)](https://github.com/samuelcolvin/watchfiles/blob/main/LICENSE)

Simple, modern and high performance file watching and code reload in python.

---

**Documentation**: [watchfiles.helpmanual.io](https://watchfiles.helpmanual.io)

**Source Code**: [github.com/samuelcolvin/watchfiles](https://github.com/samuelcolvin/watchfiles)

---

Underlying file system notifications are handled by the [Notify](https://github.com/notify-rs/notify) rust library.

This package was previously named "watchgod",
see [the migration guide](https://watchfiles.helpmanual.io/migrating/) for more information.

## Installation

**watchfiles** requires Python 3.9 - 3.14.

```bash
pip install watchfiles
```

Binaries are available for most architectures on Linux, MacOS and Windows ([learn more](https://watchfiles.helpmanual.io/#installation)).

Otherwise, you can install from source which requires Rust stable to be installed.

## Usage

Here are some examples of what **watchfiles** can do:

### `watch` Usage

```py
from watchfiles import watch

for changes in watch('./path/to/dir'):
    print(changes)
```
See [`watch` docs](https://watchfiles.helpmanual.io/api/watch/#watchfiles.watch) for more details.

### `awatch` Usage

```py
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](https://watchfiles.helpmanual.io/api/watch/#watchfiles.awatch) for more details.

### `run_process` Usage

```py
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](https://watchfiles.helpmanual.io/api/run_process/#watchfiles.run_process) for more details.

### `arun_process` Usage

```py
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](https://watchfiles.helpmanual.io/api/run_process/#watchfiles.arun_process) for more details.

## CLI

**watchfiles** also comes with a CLI for running and reloading code. To run `some command` when files in `src` change:

```
watchfiles "some command" src
```

For more information, see [the CLI docs](https://watchfiles.helpmanual.io/cli/).

Or run

```bash
watchfiles --help
```

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v1.2.0` | 2026-05-18 | High | ## What's Changed * ci: add riscv64 manylinux wheels by @justeph in https://github.com/samuelcolvin/watchfiles/pull/359 * fix linting by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/370 * Add Python 3.15-dev build, drop 3.9, increase MVRV to 1.83 by @simonw in https://github.com/samuelcolvin/watchfiles/pull/369 * fix: improve type safety and error handling by @N3XT3R1337 in https://github.com/samuelcolvin/watchfiles/pull/365 * Ruff target version to 3.10 by @samuelcolvin |
| `1.1.1` | 2026-04-21 | Low | Imported from PyPI (1.1.1) |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |
| `v1.1.1` | 2025-10-14 | Low | ## What's Changed * Add support for Python 3.14 on windows builds by @zerocewl in https://github.com/samuelcolvin/watchfiles/pull/352 * prepare for v1.1.1 release by @samuelcolvin in https://github.com/samuelcolvin/watchfiles/pull/353  ## New Contributors * @zerocewl made their first contribution in https://github.com/samuelcolvin/watchfiles/pull/352  **Full Changelog**: https://github.com/samuelcolvin/watchfiles/compare/v1.1.0...v1.1.1 |

## Citation

- HTML: https://www.freshcrate.ai/projects/watchfiles
- Markdown: https://www.freshcrate.ai/projects/watchfiles.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/watchfiles/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._