django-axes

8.3.1 · active · verified Sat Apr 11

django-axes is a Django plugin that actively monitors and tracks suspicious login attempts, helping to protect Django-powered sites from brute-force attacks. It can lock out users or IP addresses after a configurable number of failed attempts, supporting various tracking methods like IP, username, and user agent combinations. The library is currently at version 8.3.1 and is actively maintained by the Jazzband community, with a regular release cadence.

Warnings

breaking Version 8.0.0 moved all database-related logic into `axes.handlers.database.AxesDatabaseHandler`. If you had custom handlers or directly accessed internal database functions related to attempts, you will need to refactor your code to use the new handler methods.
Fix: Review `axes.handlers.database.AxesDatabaseHandler` for new API calls and refactor any custom logic. Refer to the upgrade notes for specific changes.
breaking Version 7.0.0 introduced significant breaking changes related to dynamic cooloff time calculation and lockout response handling. The lockout response calculation changed to request flagging instead of throwing exceptions, and `axes.request.AxesHttpRequest` object type definition was deprecated.
Fix: Consult the version 7 upgrade notes in the official documentation. This will likely involve changes if you customized lockout responses or relied on the deprecated `AxesHttpRequest` object.
gotcha As of version 7.0.2, `AXES_USERNAME_FORM_FIELD` now defaults to `settings.AUTH_USER_MODEL.USERNAME_FIELD`. Previously, it hardcoded to 'username'. If you use a custom user model with a different username field or a custom login form with a non-standard username field name (e.g., 'email'), you must explicitly set `AXES_USERNAME_FORM_FIELD` in your `settings.py` to prevent `AccessAttempt` records from having a `None` username.
Fix: Explicitly define `AXES_USERNAME_FORM_FIELD = 'your_username_field_name'` in `settings.py` to match your user model's `USERNAME_FIELD` or your login form's username field.
gotcha Incorrect order of `AUTHENTICATION_BACKENDS` can lead to axes not functioning correctly. `AxesStandaloneBackend` (or `AxesBackend`) *must* be the first item in your `AUTHENTICATION_BACKENDS` list in `settings.py`.
Fix: Ensure `AUTHENTICATION_BACKENDS = ['axes.backends.AxesStandaloneBackend', 'django.contrib.auth.backends.ModelBackend', ...]`.
gotcha If using a multi-process server (e.g., Gunicorn with multiple workers) or a distributed environment, using `django.core.cache.backends.locmem.LocMemCache` or `FileBasedCache` as your cache backend can lead to inconsistent behavior for Axes, as attempts might not be shared across processes.
Fix: Configure a persistent and shared cache backend like Memcached or Redis (`django.core.cache.backends.memcached.MemcachedCache`, `django.core.cache.backends.redis.RedisCache`) for accurate tracking across multiple processes.
gotcha Prior to version 5.32, a common behavior was that the cool-off timer would reset on any subsequent failed login attempts during an existing lockout period. This could inadvertently extend the lockout time indefinitely.
Fix: Upgrade to `django-axes` 5.32 or newer and set `AXES_RESET_COOL_OFF_ON_FAILURE_DURING_LOCKOUT = False` in your `settings.py` to prevent the cool-off period from resetting.

Install

pip install django-axes Install stable release

Imports

AxesStandaloneBackend
```
from axes.backends import AxesStandaloneBackend
```
While `AxesBackend` is available for backward compatibility, `AxesStandaloneBackend` is recommended as it doesn't provide permissions-checking functionality, allowing for custom logic if needed. It must be at the top of your `AUTHENTICATION_BACKENDS` list.
AxesMiddleware
```
from axes.middleware import AxesMiddleware
```
This middleware handles lockout responses. It should typically be the last middleware in your `MIDDLEWARE` list.
axes.signals.user_locked_out
```
from django.dispatch import receiver
from axes.signals import user_locked_out
```
Used for custom actions when a user is locked out, e.g., integration with Django REST Framework for custom API responses.
axes.decorators.axes_prevent_lockout
```
from axes.decorators import axes_prevent_lockout
```
Decorator to prevent a view from triggering axes lockout logic.

Quickstart

To quickly set up django-axes, add 'axes' to `INSTALLED_APPS`, configure `AUTHENTICATION_BACKENDS` to include `AxesStandaloneBackend` at the top, and add `AxesMiddleware` to your `MIDDLEWARE` list, preferably at the end. Finally, run `migrate` to create necessary database tables and `check` to verify your configuration. You can then adjust settings like `AXES_FAILURE_LIMIT` and `AXES_COOLOFF_TIME`.

# settings.py

INSTALLED_APPS = [
    # ... other Django apps
    'axes',
]

AUTHENTICATION_BACKENDS = [
    'axes.backends.AxesStandaloneBackend',  # Must be first
    'django.contrib.auth.backends.ModelBackend',
]

MIDDLEWARE = [
    # ... other Django middleware
    'axes.middleware.AxesMiddleware',  # Should be last if overriding auth response
]

# Optional: Basic configuration
AXES_FAILURE_LIMIT = 5
AXES_COOLOFF_TIME = 60 # In minutes or timedelta object (e.g., timedelta(minutes=30))
# AXES_LOCK_OUT_BY_IP_OR_USERNAME = True # Lock out by IP or username, not both

# Then, run migrations:
# python manage.py migrate
# And check your configuration:
# python manage.py check

view raw JSON →