Registry / web-framework / django-maintenance-mode

django-maintenance-mode

JSON →
library0.22.0pypypiunverified

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.

pip install django-maintenance-mode
INSTALL
IMPORT
SIG · DJANGO-MAINTENANCE
D
django-maintenance-mode
web-frameworkpythonv0.22.0
Install
1.6s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.22.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.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.2MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage

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

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

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
Debug
Known issues
breakingVersion 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.
affects: 0.22.0+
breakingThe 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.
affects: 0.21.0+
gotchaThe `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.
affects: <0.22.0
gotchaThe `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).
affects: 0.21.0+
Upgrade
Version history
0.22.0latest on PyPI · released Apr 3, 2025
Audit
Dependencies
DjangorequiredThis is a Django middleware and requires Django to function.
Agent activity
2 hits · last 30 days
node
2
Resources
django-maintenance-mode — pip install django-maintenance-mode · libregistry