Skip to main content

​
Overview

This guide helps you upgrade django-allauth to newer versions safely and efficiently. Always review the Changelog and Breaking Changes before upgrading.

​
General Upgrade Process

1

Review the Changelog

Check the Changelog for all versions between your current version and the target version. Pay special attention to:
  • Security notices
  • Breaking changes
  • Deprecated features
  • New configuration requirements
2

Update Dependencies

Update django-allauth in your requirements file:
pip install --upgrade django-allauth
Check if you need to update optional dependencies:
pip install --upgrade "django-allauth[mfa,socialaccount,saml]"
3

Run Database Migrations

Apply any new database migrations:
python manage.py migrate
Always backup your database before running migrations in production.
4

Update Configuration

Review and update your settings based on the changelog:
  • Add new required settings
  • Update deprecated settings
  • Review security-related configuration changes
5

Test Thoroughly

Test all authentication flows:
  • Local signup and login
  • Social authentication
  • Password reset
  • Email verification
  • MFA if enabled
  • API endpoints if using headless mode

​
Upgrading to 65.x

​
Security: IP Address Detection

Starting with version 65.14.2, X-Forwarded-For is distrusted by default for IP address detection.
You must configure IP detection based on your deployment: Option 1: Configure Trusted Proxy Count
settings.py
# If behind 1 proxy (e.g., nginx)
ALLAUTH_TRUSTED_PROXY_COUNT = 1

# If behind 2 proxies (e.g., load balancer + nginx)
ALLAUTH_TRUSTED_PROXY_COUNT = 2
Option 2: Use Trusted Client IP Header
settings.py
# If your infrastructure sets a trusted header
ALLAUTH_TRUSTED_CLIENT_IP_HEADER = "HTTP_CF_CONNECTING_IP"  # Cloudflare
# or
ALLAUTH_TRUSTED_CLIENT_IP_HEADER = "HTTP_X_REAL_IP"  # nginx
Option 3: Custom Implementation
adapters.py
from allauth.account.adapter import DefaultAccountAdapter

class MyAccountAdapter(DefaultAccountAdapter):
    def get_client_ip(self, request):
        # Your custom logic
        return request.META.get('HTTP_CF_CONNECTING_IP')

​
Django 6.0 Support

Django 6.0 is officially supported as of version 65.13.1. No configuration changes required.

​
Headless JWT Algorithm

The JWT algorithm is now configurable (version 65.14.0):
settings.py
HEADLESS_TOKEN_STRATEGY = {
    "type": "jwt",
    "signing_key": SECRET_KEY,
    "algorithm": "HS256",  # Now configurable, defaults to RS256
}

​
Upgrading to 64.x

​
Python Version Requirements

Django Allauth 64.x requires Python 3.8 or higher. If you’re on Python 3.7 or earlier:
  1. Upgrade Python to 3.8+
  2. Test your application thoroughly
  3. Then upgrade django-allauth

​
Template Changes

Version 64 introduced the element-based styling system. If you have custom templates:
settings.py
# Enable the new system (recommended)
ACCOUNT_FORMS = {
    "login": "allauth.account.forms.LoginForm",
}
Or continue using legacy templates:
settings.py
ACCOUNT_TEMPLATE_EXTENSION = "html"  # Instead of default "html"

​
Version-Specific Upgrade Notes

​
Rate Limiting Security

The default behavior for IP address detection has changed. See the security section above.

​
SAML RelayState Security

If you use SAML with IdP-initiated SSO enabled:
settings.py
SOCIALACCOUNT_PROVIDERS = {
    'saml': {
        'APPS': [...],
        # Ensure you validate relay states
    }
}

​
Template System Updates

The element-based template system was introduced. Custom templates may need updates.

​
Form Changes

Some form fields and validation logic changed. Review custom forms.

​
Settings Reorganization

Some settings were renamed or reorganized:
# Old (63.x)
ACCOUNT_EMAIL_VERIFICATION = "mandatory"

# New (64.x) - still supported
ACCOUNT_EMAIL_VERIFICATION = "mandatory"
No breaking changes in settings, but new options available.

​
Testing Your Upgrade

​
Automated Tests

Add these tests to verify the upgrade:
tests.py
from django.test import TestCase
from django.contrib.auth import get_user_model
from allauth.account.models import EmailAddress

class UpgradeTests(TestCase):
    def test_signup_flow(self):
        """Test basic signup still works"""
        response = self.client.post('/accounts/signup/', {
            'email': 'test@example.com',
            'password1': 'testpass123',
            'password2': 'testpass123',
        })
        self.assertEqual(response.status_code, 302)
        
    def test_login_flow(self):
        """Test login still works"""
        User = get_user_model()
        user = User.objects.create_user('testuser', 'test@example.com', 'testpass123')
        EmailAddress.objects.create(user=user, email='test@example.com', verified=True, primary=True)
        
        response = self.client.post('/accounts/login/', {
            'login': 'test@example.com',
            'password': 'testpass123',
        })
        self.assertEqual(response.status_code, 302)

​
Manual Testing Checklist

  • Signup with email
  • Login with username/email
  • Password reset flow
  • Email verification
  • Social login (test each provider you use)
  • MFA enrollment and authentication
  • Account management (change email, change password)
  • Headless API endpoints (if applicable)
  • Rate limiting works correctly
  • Admin panel access

​
Rollback Plan

If issues occur after upgrading:
1

Restore Database Backup

Restore your database from the backup taken before migration
2

Downgrade Package

Pin to the previous version:
pip install django-allauth==<previous-version>
3

Reverse Migrations

If you applied new migrations:
python manage.py migrate allauth <previous-migration>

​
Getting Help

If you encounter issues during upgrade:

Stack Overflow

Ask questions with the django-allauth tag

Issue Tracker

Report bugs or unexpected behavior

Breaking Changes

Review detailed breaking changes

Changelog

See all version changes