Registry / web-framework / django-watchfiles

django-watchfiles

library1.4.0pypiunverified

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.

web-framework

pip install django-watchfiles

INSTALL

IMPORT

SIG · DJANGO-WATCHFILES

django-watchfiles

web-frameworkenv1.4.0

Install

3.9s avg

Import

—

Disk

69MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · 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.910 runs

installs and imports cleanly · install 0.0s · import 0.000s · 70MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.9s · import 0.000s · 70MB

69MB installed

● package 69MB

Code

Verified usage

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

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.

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']

Debug

Known issues

breakingdjango-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`.

affects: >=1.0.0

gotchadjango-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.

affects: All

gotchaFiles 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']`.

affects: All

breakingdjango-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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'django_watchfiles'

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.

`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'

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`.

Upgrade

Version history

1.4.0latest on PyPI · released Sep 22, 2025

Audit

Dependencies

DjangorequiredCore framework dependency; requires >=3.2

watchfilesrequiredThe underlying file watcher library; requires >=0.17.0

Agent activity

2 hits · last 30 days

node

Resources

No resource links recorded.