Django Watchfiles

1.4.0 · active · verified Thu Apr 16

django-watchfiles is a Django package that enhances Django's built-in autoreloader by utilizing the more efficient `watchfiles` library. It provides faster and more reliable file change detection during development, leading to quicker server reloads. The current version is 1.4.0. It has an active but infrequent release cadence, typically releasing new versions as `watchfiles` or Django versions evolve.

Common errors

```
ModuleNotFoundError: No module named 'django_watchfiles'
```
cause The `django-watchfiles` package is not installed in your current Python environment.

fix Run `pip install django-watchfiles`.
```
Changes to Python files (or other watched files) are not triggering the Django development server to reload.
```
cause `django_watchfiles` is likely not added to `INSTALLED_APPS`, or `settings.DEBUG` is set to `False`.

fix Ensure `'django_watchfiles'` is present in your `INSTALLED_APPS` list and `DEBUG = True` in your `settings.py`.
```
ImportError: cannot import name 'FileWatcher' from 'watchfiles'
```
cause The `watchfiles` dependency is too old for the installed `django-watchfiles` version (e.g., using `django-watchfiles>=1.0` with `watchfiles<0.17.0`).

fix Upgrade `watchfiles` to a compatible version: `pip install --upgrade watchfiles`.

Warnings

breaking django-watchfiles v1.0 and later require watchfiles version 0.17.0 or newer. Older watchfiles versions are incompatible and will lead to errors.
Fix: Upgrade watchfiles: `pip install --upgrade watchfiles`.
gotcha django-watchfiles, like Django's default autoreloader, only functions when `settings.DEBUG` is set to `True`. It has no effect in production environments.
Fix: Ensure `DEBUG = True` in your `settings.py` for local development. Do not use it in production.
gotcha Files changed outside your project's root directory or an explicitly configured `WATCHFILES_WATCH_DIR` will not trigger reloads. Ensure all relevant files are within the watched paths.
Fix: If needed, set `WATCHFILES_WATCH_DIR` in `settings.py` to a more encompassing path, or specify multiple paths in a list: `WATCHFILES_WATCH_DIR = ['/path/to/project', '/path/to/another/watched/dir']`.
breaking django-watchfiles requires Django 3.2 or newer. Older Django versions are not supported.
Fix: Upgrade your Django project to Django 3.2 or a later version.

Install

pip install django-watchfiles Install stable version

Imports

WatchfilesAppConfig
```
from django_watchfiles.apps import WatchfilesAppConfig
```
This AppConfig is automatically discovered by Django when 'django_watchfiles' is in INSTALLED_APPS. Direct import for user code is extremely rare and generally unnecessary.

Quickstart

Install the package and add 'django_watchfiles' to your Django project's INSTALLED_APPS in `settings.py`. Ensure `DEBUG = True` for autoreloading to be active. Run `python manage.py runserver` as usual.

INSTALLED_APPS = [
    # ... other apps ...
    'django_watchfiles',
]

# Optional: Customize watch directory (default is project root)
# WATCHFILES_WATCH_DIR = '/path/to/your/custom/dir'

# Optional: Ignore specific patterns (default includes common ignores)
# WATCHFILES_IGNORE_PATTERNS = ['__pycache__/', '*.log']

view raw JSON →