Skip to main content

​
Overview

This page documents breaking changes that may require code updates when upgrading django-allauth. Always review these changes before upgrading to a new major version.
Breaking changes can affect your application’s functionality. Test thoroughly in a staging environment before deploying to production.

​
Version 65.x

​
IP Address Detection (65.14.2)

Critical Security Change
What Changed: The default IP address detection no longer trusts X-Forwarded-For header. Impact: Rate limiting may not work correctly if not configured properly. Required Action: Configure IP detection for your deployment architecture.
settings.py
# Choose one of these approaches:

# Option 1: Configure proxy count
ALLAUTH_TRUSTED_PROXY_COUNT = 1  # Number of proxies in front of Django

# Option 2: Use a trusted header
ALLAUTH_TRUSTED_CLIENT_IP_HEADER = "HTTP_CF_CONNECTING_IP"

# Option 3: Override in adapter
class MyAccountAdapter(DefaultAccountAdapter):
    def get_client_ip(self, request):
        return request.META.get('HTTP_CF_CONNECTING_IP')
Migration Path:
  1. Identify your deployment architecture (direct, behind nginx, behind load balancer, etc.)
  2. Choose the appropriate configuration method
  3. Test rate limiting functionality
  4. Monitor for any IP detection issues

​
Version 64.x

​
Python 3.7 Support Dropped

What Changed: Python 3.8+ is now required. Impact: Applications running on Python 3.7 or earlier cannot use django-allauth 64.x+. Required Action: Upgrade to Python 3.8 or higher before upgrading django-allauth.

​
Template System Changes

What Changed: Introduction of element-based styling system. Impact: Custom templates may need updates to use the new system. Migration Path: Option 1: Adopt New System (Recommended)
settings.py
# Use new element-based templates
TEMPLATES = [
    {
        'DIRS': [BASE_DIR / 'templates'],
        # ...
    },
]
Create element overrides:
templates/allauth/elements/button.html
<button class="btn btn-primary" type="{{ type }}">
    {{ content }}
</button>
Option 2: Continue with Legacy Templates
settings.py
# Keep using your existing custom templates
# No configuration needed if templates already exist

​
Version 63.x

​
Django 3.2 Support Dropped

What Changed: Django 4.2+ is now required. Impact: Projects on Django 3.2 or earlier need to upgrade Django first. Required Action: Upgrade to Django 4.2 LTS before upgrading django-allauth.

​
Version 62.x

​
Headless API Token Format

What Changed: JWT token structure and validation updated. Impact: Existing tokens may need to be refreshed. Migration Path:
  1. Update frontend to handle new token format
  2. Existing tokens remain valid until expiry
  3. New tokens use updated format

​
Version 60.x

​
MFA Models Changes

What Changed: MFA models were restructured for better extensibility. Impact: Custom MFA implementations need updates. Required Action: Run migrations and update custom MFA code. 
python manage.py migrate allauth
If you have custom MFA authenticators: 
# Old (59.x)
from allauth.mfa.models import TOTPDevice

# New (60.x)
from allauth.mfa.models import Authenticator
authenticator = Authenticator.objects.filter(
    user=user,
    type=Authenticator.Type.TOTP
).first()

​
Common Migration Patterns

​
Updating Settings

Old Approach (Pre-65.x):
# Rate limiting worked without explicit IP configuration
ACCOUNT_RATE_LIMITS = {
    "login": "5/m",
}
New Approach (65.x+):
# Must configure IP detection
ALLAUTH_TRUSTED_PROXY_COUNT = 1

ACCOUNT_RATE_LIMITS = {
    "login": "5/m",
}
Old Approach (Pre-64.x):
templates/account/login.html
{% extends "account/base.html" %}
{% block content %}
  <form method="post">
    {% csrf_token %}
    {{ form.as_p }}
    <button type="submit">Login</button>
  </form>
{% endblock %}
New Approach (64.x+):
templates/allauth/layouts/entrance.html
{% extends 'allauth/layouts/base.html' %}
{% block content %}
  <div class="container">
    {% block entrance_content %}{% endblock %}
  </div>
{% endblock %}
Or use element overrides:
templates/allauth/elements/button.html
<button class="btn btn-primary" type="{{ type }}">
  {{ content }}
</button>

​
Updating Code

Some adapter methods have been updated. Check if you override any:
class MyAccountAdapter(DefaultAccountAdapter):
    # New in 65.x - must implement if using rate limiting
    def get_client_ip(self, request):
        return request.META.get('REMOTE_ADDR')
    
    # Updated signature in 64.x
    def save_user(self, request, user, form, commit=True):
        # New parameter: commit
        user = super().save_user(request, user, form, commit=commit)
        return user
Signal arguments remain backward compatible, but new parameters added:
from allauth.account.signals import user_signed_up

@receiver(user_signed_up)
def on_user_signed_up(sender, request, user, **kwargs):
    # Always use **kwargs to handle new parameters in future versions
    sociallogin = kwargs.get('sociallogin')
    if sociallogin:
        # Handle social signup
        pass

​
Testing for Breaking Changes

​
Automated Detection

Add these tests to detect breaking changes:
tests/test_compatibility.py
from django.test import TestCase
import allauth

class CompatibilityTests(TestCase):
    def test_version_requirements(self):
        """Ensure version meets requirements"""
        import django
        import sys
        
        # Check Python version
        self.assertGreaterEqual(sys.version_info[:2], (3, 8))
        
        # Check Django version
        django_version = tuple(map(int, django.VERSION[:2]))
        self.assertGreaterEqual(django_version, (4, 2))
    
    def test_required_settings(self):
        """Check required settings are configured"""
        from django.conf import settings
        
        # Check IP detection is configured (65.x+)
        has_proxy_config = hasattr(settings, 'ALLAUTH_TRUSTED_PROXY_COUNT')
        has_header_config = hasattr(settings, 'ALLAUTH_TRUSTED_CLIENT_IP_HEADER')
        
        self.assertTrue(
            has_proxy_config or has_header_config,
            "Must configure IP detection in 65.x+"
        )

​
Manual Testing

After upgrading, test these critical flows:
1

Authentication

  • Login with username
  • Login with email
  • Social login
  • MFA authentication
2

Rate Limiting

  • Trigger rate limits
  • Verify IP detection
  • Check rate limit messages
3

Templates

  • Check all authentication pages
  • Verify custom templates still work
  • Test responsive design
4

API (if applicable)

  • Test headless endpoints
  • Verify token format
  • Check CORS configuration

​
Version Compatibility Matrix

django-allauthPythonDjangoNotes
65.x3.8+4.2, 5.0, 5.1, 5.2, 6.0Current version
64.x3.8+4.2, 5.0, 5.1Template system changes
63.x3.8+4.2, 5.0Django 3.2 support dropped
62.x3.7+3.2, 4.0, 4.1Last version with Python 3.7

​
Getting Help

If you encounter issues with breaking changes:

Upgrade Guide

Step-by-step upgrade instructions

Changelog

Detailed version history

Stack Overflow

Ask the community

Issue Tracker

Report upgrade issues

Build docs developers (and LLMs) love

Get started for freeTalk to us