{"id":14531,"library":"django-watchfiles","title":"Django Watchfiles","description":"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.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/adamchainz/django-watchfiles","tags":["django","autoreload","development","hot-reloading","file-watcher"],"install":[{"cmd":"pip install django-watchfiles","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core framework dependency; requires >=3.2","package":"Django","optional":false},{"reason":"The underlying file watcher library; requires >=0.17.0","package":"watchfiles","optional":false}],"imports":[{"note":"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.","symbol":"WatchfilesAppConfig","correct":"from django_watchfiles.apps import WatchfilesAppConfig"}],"quickstart":{"code":"INSTALLED_APPS = [\n    # ... other apps ...\n    'django_watchfiles',\n]\n\n# Optional: Customize watch directory (default is project root)\n# WATCHFILES_WATCH_DIR = '/path/to/your/custom/dir'\n\n# Optional: Ignore specific patterns (default includes common ignores)\n# WATCHFILES_IGNORE_PATTERNS = ['__pycache__/', '*.log']","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade watchfiles: `pip install --upgrade watchfiles`.","message":"django-watchfiles v1.0 and later require watchfiles version 0.17.0 or newer. Older watchfiles versions are incompatible and will lead to errors.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `DEBUG = True` in your `settings.py` for local development. Do not use it in production.","message":"django-watchfiles, like Django's default autoreloader, only functions when `settings.DEBUG` is set to `True`. It has no effect in production environments.","severity":"gotcha","affected_versions":"All"},{"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']`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade your Django project to Django 3.2 or a later version.","message":"django-watchfiles requires Django 3.2 or newer. Older Django versions are not supported.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install django-watchfiles`.","cause":"The `django-watchfiles` package is not installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'django_watchfiles'"},{"fix":"Ensure `'django_watchfiles'` is present in your `INSTALLED_APPS` list and `DEBUG = True` in your `settings.py`.","cause":"`django_watchfiles` is likely not added to `INSTALLED_APPS`, or `settings.DEBUG` is set to `False`.","error":"Changes to Python files (or other watched files) are not triggering the Django development server to reload."},{"fix":"Upgrade `watchfiles` to a compatible version: `pip install --upgrade 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`).","error":"ImportError: cannot import name 'FileWatcher' from 'watchfiles'"}],"ecosystem":"pypi"}