watchgod

library0.8.2pypypi✓ verified 22d ago

Watchgod is a Python library designed for simple file watching and code reloading. It was last released as version 0.8.2 in April 2022. This package is now considered inactive and has been superseded by `watchfiles`, which offers a more performant Rust-based backend for file system notifications. `watchgod` relies on file polling for change detection.

devops observability

pip install watchgod

github ↗package ↗

INSTALL

IMPORT

SIG · WATCHGOD

watchgod

devopspythonv0.8.2

Install

1.8s avg

Import

336ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.2 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.360s · 19.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.312s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

watch

✓ from watchgod import watch

awatch

✓ from watchgod import awatch

run_process

✓ from watchgod import run_process

arun_process

✓ from watchgod import arun_process

This quickstart demonstrates how to use `watchgod.watch` to detect file system changes in a specified directory. It creates a temporary directory and file, then watches it for a short period. For real-world use, you would typically run the `watch` loop indefinitely.

import time from watchgod import watch import os def main(): # Create a dummy directory and file for demonstration if not os.path.exists('watched_dir'): os.makedirs('watched_dir') with open('watched_dir/test.txt', 'w') as f: f.write('initial content') print("Watching './watched_dir' for changes (will run for 5 seconds)...") # The 'watch' function yields sets of changed files # In a real application, you'd typically run this indefinitely # or within a controlled loop. # For this quickstart, we'll simulate a short watch period. # Note: watchgod uses polling, so changes might not be immediate. start_time = time.time() for changes in watch('./watched_dir'): print(f"Detected changes: {changes}") if time.time() - start_time > 5: # Limit execution time for quickstart break print("Quickstart demonstration complete.") if __name__ == '__main__': main()

watchgod --version

Debug

Known issues

breakingThis package (watchgod) has been renamed to `watchfiles` and is no longer actively developed. The `watchgod` package will only receive critical security fixes. Users are strongly encouraged to migrate to `watchfiles` for new projects and to update existing `watchgod` installations.

fix

Migrate to `watchfiles`. Install with `pip install watchfiles`. Update import statements from `watchgod` to `watchfiles`. Be aware of potential API changes, especially regarding `watcher_cls` (replaced by `watch_filter`) and `target` arguments for `run_process` (now keyword-only). Refer to the `watchfiles` migration guide.

affects: <=0.8.2

gotcha`watchgod` (version 0.8.2 and earlier) uses file polling to detect changes, which can be less efficient and may introduce a slight delay compared to OS-native file system notifications.

fix

For high-performance, real-time file watching, use the `watchfiles` library, its successor, which utilizes a Rust-based backend for OS-native file system event handling.

affects: <=0.8.2

deprecatedThe `Development Status :: 7 - Inactive` classifier has been added to the `watchgod` PyPI project, indicating that the project is no longer under active development.

fix

Switch to `watchfiles` to ensure you receive ongoing feature development, performance improvements, and non-critical bug fixes.

affects: <=0.8.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'watchgod'

The `watchgod` package is not installed in the current Python environment or is not accessible.

fix

pip install watchgod

watchgod not detecting changes

`watchgod` relies on file polling, which can be inefficient or unreliable in certain environments (e.g., WSL, Docker, network drives) or if the polling interval is too slow.

fix

Ensure the watched path is directly accessible and consider adjusting the `poll_interval`. For more robust, event-driven detection, migrate to `watchfiles`.

TypeError: watch() got an unexpected keyword argument 'paths'

The `watchgod.watch` function expects one or more positional arguments for the paths to watch, not a keyword argument named `paths`.

fix

from watchgod import watch

watch('.', 'src', callback=my_callback)  # Pass paths as positional arguments

ValueError: path doesn't exist

The path or one of the paths provided to the `watchgod.watch` function does not exist on the file system.

fix

from watchgod import watch
import os

# Ensure the directory exists or provide a valid path
watched_dir = 'my_project_dir'
if not os.path.exists(watched_dir):
    os.makedirs(watched_dir)
watch(watched_dir, callback=my_callback)

Upgrade

Version history

0.8.2latest on PyPI · released Apr 1, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

40 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/samuelcolvin/watchfiles ↗

packagehttps://pypi.org/project/watchgod/ ↗