{"id":8101,"library":"django-maintenance-mode","title":"django-maintenance-mode","description":"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.","status":"active","version":"0.22.0","language":"en","source_language":"en","source_url":"https://github.com/fabiocaccamo/django-maintenance-mode","tags":["django","maintenance","middleware","503","down-time"],"install":[{"cmd":"pip install django-maintenance-mode","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Django middleware and requires Django to function.","package":"Django","optional":false}],"imports":[{"note":"The library is installed as `maintenance_mode`, not `django_maintenance_mode`.","wrong":"django_maintenance_mode.middleware.MaintenanceModeMiddleware","symbol":"MaintenanceModeMiddleware","correct":"maintenance_mode.middleware.MaintenanceModeMiddleware"}],"quickstart":{"code":"import os\n\n# settings.py\nINSTALLED_APPS = [\n    # ... other apps\n    'maintenance_mode',\n]\n\nMIDDLEWARE = [\n    # ... other middleware (e.g., SessionMiddleware, CommonMiddleware)\n    'maintenance_mode.middleware.MaintenanceModeMiddleware',\n    # Place above other middleware that might serve content (e.g., WhiteNoise)\n    # Place below any middleware that identifies users if you want staff to bypass\n]\n\n# Activate maintenance mode either via settings or manage.py command\nMAINTENANCE_MODE = os.environ.get('DJANGO_MAINTENANCE_MODE', 'False').lower() == 'true'\n\n# Optional: Customize behavior\nMAINTENANCE_MODE_EXCEPT_URLS = (\n    r'^/admin/?$', # Allow admin access\n)\nMAINTENANCE_MODE_EXCEPT_STAFF = True # Allow logged-in staff users\nMAINTENANCE_MODE_REDIRECT_URL = '/503/' # Redirect to a specific URL\nMAINTENANCE_MODE_TEMPLATE = '503.html' # Use a custom template\n\n# In your project's urls.py (if using redirect or custom template path)\n# from django.urls import path\n# from django.views.generic import TemplateView\n# urlpatterns = [\n#     path('503/', TemplateView.as_view(template_name='503.html'), name='maintenance_503'),\n# ]\n\n# To toggle maintenance mode from the command line:\n# python manage.py maintenance_mode on\n# python manage.py maintenance_mode off","lang":"python","description":"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`."},"warnings":[{"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.","message":"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+).","severity":"breaking","affected_versions":"0.22.0+"},{"fix":"Update your `settings.py` to use `MAINTENANCE_MODE_GET_CONTEXT` instead of the old name.","message":"The setting `MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT` was renamed to `MAINTENANCE_MODE_GET_CONTEXT` in version 0.21.0.","severity":"breaking","affected_versions":"0.21.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.22.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"0.21.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `'maintenance_mode'` is in `INSTALLED_APPS` and `'maintenance_mode.middleware.MaintenanceModeMiddleware'` is correctly listed in `MIDDLEWARE` in your `settings.py`.","cause":"The `maintenance_mode` app is not correctly added to `INSTALLED_APPS` or there's a typo in the middleware path in `MIDDLEWARE`.","error":"ModuleNotFoundError: No module named 'maintenance_mode.middleware'"},{"fix":"Double-check the import path in `MIDDLEWARE` to ensure it is exactly `'maintenance_mode.middleware.MaintenanceModeMiddleware'`.","cause":"Typo in the middleware import path, or using an incorrect symbol name.","error":"AttributeError: 'module' object has no attribute 'MaintenanceModeMiddleware'"},{"fix":"Rename `MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT` to `MAINTENANCE_MODE_GET_CONTEXT` in your `settings.py`.","cause":"Using the deprecated setting name `MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT`.","error":"ValueError: Invalid config for MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT. Check settings.py"},{"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.","cause":"The user running the Django application (e.g., Gunicorn/uWSGI user) does not have write permissions to the default state file location.","error":"Permission denied: '/tmp/maintenance_mode_state.txt'"}]}