Django Browser Reload

1.21.0 · active · verified Tue Apr 14

django-browser-reload is a Django application that automatically refreshes your web browser during development when changes are detected in Python code, templates, or static files. It helps improve the development workflow by eliminating manual browser reloads. The current version is 1.21.0, and it actively supports Python versions 3.9 to 3.14 and Django versions 4.2 to 6.0. It is actively maintained.

Warnings

breaking The `BrowserReloadMiddleware` must be placed *after* any other middleware that encodes the response, such as Django's `GZipMiddleware`. Incorrect placement can prevent the script from being injected or cause unexpected behavior.
Fix: Ensure `django_browser_reload.middleware.BrowserReloadMiddleware` is listed after `GZipMiddleware` or similar encoding middleware in your `MIDDLEWARE` setting.
gotcha `django-browser-reload` only operates when `DEBUG = True` in your Django settings. It is a development-only tool and will not function in production environments.
Fix: Set `DEBUG = True` in your `settings.py` for development. The `__reload__` URL pattern should also ideally be conditional on `settings.DEBUG`.
gotcha The library utilizes `SharedWorker` for efficient multi-tab reloading, which was not supported by Safari prior to version 16 (released September 2022). Older Safari versions may not experience automatic reloads.
Fix: Ensure browsers used for development are modern and support `SharedWorker` (Chrome, Edge, Firefox, Opera, and Safari 16+). The library provides graceful degradation if SharedWorker is unavailable, falling back to per-tab reloading.
gotcha Using `python manage.py runserver --nothreading` will prevent `django-browser-reload` from functioning correctly, as it relies on threads to stream events indefinitely.
Fix: Avoid using the `--nothreading` option with `runserver` when using `django-browser-reload`.
gotcha When using `django-browser-reload` with Django 5.1's `LoginRequiredMiddleware`, you may need to explicitly configure `login_not_required` for the `__reload__` URL path to ensure it can be accessed without authentication.
Fix: Consult Django 5.1 documentation for `LoginRequiredMiddleware` configuration to whitelist the `__reload__` path, e.g., by using `login_not_required` attributes on the URL pattern or view.

Install

pip install django-browser-reload Install with pip

Imports

django_browser_reload

INSTALLED_APPS = [
    # ...
    'django_browser_reload',
    # ...
]

Add to INSTALLED_APPS in settings.py

BrowserReloadMiddleware
```
MIDDLEWARE = [
    # ...
    'django_browser_reload.middleware.BrowserReloadMiddleware',
    # ...
]
```
Add to MIDDLEWARE in settings.py, typically after other encoding middleware like GZipMiddleware.

django_browser_reload.urls

from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('__reload__/', include('django_browser_reload.urls')), # Only in DEBUG mode
]

Include app URLs in your project's main urls.py.

reload_script (template tag)
```
{% load django_browser_reload %}
...
<body>
    ...
    {% reload_script %}
</body>
```
Alternative to middleware for injecting the reload script on specific pages. Only renders when DEBUG is True.

Quickstart

To quickly set up `django-browser-reload`, install it via pip, then add `django_browser_reload` to your `INSTALLED_APPS` and `BrowserReloadMiddleware` to your `MIDDLEWARE` in `settings.py`. Crucially, `DEBUG` must be `True`. Finally, include `django_browser_reload.urls` in your project's main `urls.py`, ideally wrapped in a `if settings.DEBUG:` block. Once configured, run `python manage.py runserver`, and your browser will automatically refresh on code, template, or static file changes.

import os
from pathlib import Path
from django.conf import settings # Import settings to check DEBUG
from django.urls import include, path

# --- settings.py (abbreviated) ---
# Make sure DEBUG is True for development
DEBUG = True

# Required for static files
INSTALLED_APPS = [
    # ... existing Django apps
    'django.contrib.staticfiles',
    'django_browser_reload',
]

# Add BrowserReloadMiddleware to your MIDDLEWARE list
# It should come after any middleware that encodes the response (e.g., GZipMiddleware)
MIDDLEWARE = [
    # ... existing middleware
    'django_browser_reload.middleware.BrowserReloadMiddleware',
]

# --- urls.py (abbreviated) ---
# Include django-browser-reload's URLs
urlpatterns = [
    path('admin/', admin.site.urls),
]

# Conditionally add the reload URLs in DEBUG mode
if settings.DEBUG:
    urlpatterns += [
        path("__reload__/", include("django_browser_reload.urls")),
    ]

# To run:
# 1. Ensure you have a Django project set up.
# 2. Add the above settings and URL patterns.
# 3. Run: python manage.py runserver
# 4. Open your browser to http://127.0.0.1:8000/ and modify a Python file, template, or static file.

view raw JSON →