django-maintenance-mode

0.22.0 · active · verified Thu Apr 16

django-maintenance-mode is a middleware that shows a 503 error page to users when maintenance mode is active in a Django project. The current version is 0.22.0. It maintains an active release cadence, frequently updating to support new Python and Django versions.

Common errors

```
ModuleNotFoundError: No module named 'maintenance_mode.middleware'
```
cause The `maintenance_mode` app is not correctly added to `INSTALLED_APPS` or there's a typo in the middleware path in `MIDDLEWARE`.

fix Ensure `'maintenance_mode'` is in `INSTALLED_APPS` and `'maintenance_mode.middleware.MaintenanceModeMiddleware'` is correctly listed in `MIDDLEWARE` in your `settings.py`.
```
AttributeError: 'module' object has no attribute 'MaintenanceModeMiddleware'
```
cause Typo in the middleware import path, or using an incorrect symbol name.

fix Double-check the import path in `MIDDLEWARE` to ensure it is exactly `'maintenance_mode.middleware.MaintenanceModeMiddleware'`.
```
ValueError: Invalid config for MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT. Check settings.py
```
cause Using the deprecated setting name `MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT`.

fix Rename `MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT` to `MAINTENANCE_MODE_GET_CONTEXT` in your `settings.py`.
```
Permission denied: '/tmp/maintenance_mode_state.txt'
```
cause The user running the Django application (e.g., Gunicorn/uWSGI user) does not have write permissions to the default state file location.

fix Ensure the user has write permissions to the `/tmp` directory or define a custom `MAINTENANCE_MODE_STATE_FILE_PATH` in `settings.py` to a directory with appropriate permissions, and then `chown` or `chmod` that directory accordingly.

Warnings

breaking Version 0.22.0 dropped support for Python 3.8, 3.9 and Django 3.x. Ensure your environment meets the new minimum requirements (Python 3.10+ and Django 4.2+).
Fix: Upgrade your Python and Django versions to supported ones (e.g., Python 3.10+, Django 4.2+). Check the project's README for the latest compatibility matrix.
breaking The setting `MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT` was renamed to `MAINTENANCE_MODE_GET_CONTEXT` in version 0.21.0.
Fix: Update your `settings.py` to use `MAINTENANCE_MODE_GET_CONTEXT` instead of the old name.
gotcha The `manage.py maintenance_mode on/off` commands interact with a state file. In older versions, this could sometimes lead to permission issues, especially if the file was created with different user permissions.
Fix: Ensure the user running the Django process (e.g., Gunicorn, uWSGI) has write permissions to the directory where the state file (`maintenance_mode_state.txt`) is stored, or upgrade to 0.22.0+ which includes fixes for this specific issue.
gotcha The `Retry-After` HTTP header in the 503 response is only set if `MAINTENANCE_MODE_RETRY_AFTER` is explicitly configured to a non-zero or non-None value. By default, it might not be included.
Fix: If you require the `Retry-After` header for SEO or client-side retry logic, explicitly set `MAINTENANCE_MODE_RETRY_AFTER` in your `settings.py` to a positive integer (e.g., `3600` for 1 hour).

Install

pip install django-maintenance-mode Install latest version

Imports

MaintenanceModeMiddleware
wrong:
```
django_maintenance_mode.middleware.MaintenanceModeMiddleware
```
correct:
```
maintenance_mode.middleware.MaintenanceModeMiddleware
```
The library is installed as `maintenance_mode`, not `django_maintenance_mode`.

Quickstart

To enable maintenance mode, add `maintenance_mode` to your `INSTALLED_APPS` and `maintenance_mode.middleware.MaintenanceModeMiddleware` to your `MIDDLEWARE`. You can activate maintenance mode by setting `MAINTENANCE_MODE = True` in your settings or by using the `python manage.py maintenance_mode on` command. Configure exceptions for URLs, staff users, or specific IP addresses using settings like `MAINTENANCE_MODE_EXCEPT_URLS` and `MAINTENANCE_MODE_EXCEPT_STAFF`.

import os

# settings.py
INSTALLED_APPS = [
    # ... other apps
    'maintenance_mode',
]

MIDDLEWARE = [
    # ... other middleware (e.g., SessionMiddleware, CommonMiddleware)
    'maintenance_mode.middleware.MaintenanceModeMiddleware',
    # Place above other middleware that might serve content (e.g., WhiteNoise)
    # Place below any middleware that identifies users if you want staff to bypass
]

# Activate maintenance mode either via settings or manage.py command
MAINTENANCE_MODE = os.environ.get('DJANGO_MAINTENANCE_MODE', 'False').lower() == 'true'

# Optional: Customize behavior
MAINTENANCE_MODE_EXCEPT_URLS = (
    r'^/admin/?$', # Allow admin access
)
MAINTENANCE_MODE_EXCEPT_STAFF = True # Allow logged-in staff users
MAINTENANCE_MODE_REDIRECT_URL = '/503/' # Redirect to a specific URL
MAINTENANCE_MODE_TEMPLATE = '503.html' # Use a custom template

# In your project's urls.py (if using redirect or custom template path)
# from django.urls import path
# from django.views.generic import TemplateView
# urlpatterns = [
#     path('503/', TemplateView.as_view(template_name='503.html'), name='maintenance_503'),
# ]

# To toggle maintenance mode from the command line:
# python manage.py maintenance_mode on
# python manage.py maintenance_mode off

view raw JSON →