Install & Compatibility
Where this runs
tested against v1.21.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 66.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.4s · import 0.000s · 67MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
django_browser_reload
✓ INSTALLED_APPS = [
# ...
'django_browser_reload',
# ...
]
✗ INSTALLED_APPS = [
# ...
'django_browser_reload',
# ...
]
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.
Debug
Known issues
breakingThe `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.fixEnsure `django_browser_reload.middleware.BrowserReloadMiddleware` is listed after `GZipMiddleware` or similar encoding middleware in your `MIDDLEWARE` setting.
affects: All versions
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.fixSet `DEBUG = True` in your `settings.py` for development. The `__reload__` URL pattern should also ideally be conditional on `settings.DEBUG`.
affects: All versions
gotchaThe 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.fixEnsure 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.
affects: < 1.13.0 (for Safari compatibility specifics), generally all versions for browser requirement.
gotchaUsing `python manage.py runserver --nothreading` will prevent `django-browser-reload` from functioning correctly, as it relies on threads to stream events indefinitely.fixAvoid using the `--nothreading` option with `runserver` when using `django-browser-reload`.
affects: All versions
gotchaWhen 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.fixConsult 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.
affects: Django 5.1+
Upgrade
Version history
1.21.0latest on PyPI · released Sep 22, 2025
Audit
Dependencies
django.contrib.staticfilesrequiredRequired for static file detection and serving assets.