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
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
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]"
Run Database Migrations
Apply any new database migrations: Always backup your database before running migrations in production.
Update Configuration
Review and update your settings based on the changelog:
Add new required settings
Update deprecated settings
Review security-related configuration changes
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 # 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 # 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 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):
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:
Upgrade Python to 3.8+
Test your application thoroughly
Then upgrade django-allauth
Template Changes Version 64 introduced the element-based styling system. If you have custom templates:
# Enable the new system (recommended) ACCOUNT_FORMS = { "login" : "allauth.account.forms.LoginForm" , }
Or continue using legacy templates:
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: SOCIALACCOUNT_PROVIDERS = { 'saml' : { 'APPS' : [ ... ], # Ensure you validate relay states } }
Template System Updates The element-based template system was introduced. Custom templates may need updates. 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:
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' : '[email protected] ' , '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' , '[email protected] ' , 'testpass123' ) EmailAddress.objects.create( user = user, email = '[email protected] ' , verified = True , primary = True ) response = self .client.post( '/accounts/login/' , { 'login' : '[email protected] ' , 'password' : 'testpass123' , }) self .assertEqual(response.status_code, 302 )
Manual Testing Checklist Rollback Plan If issues occur after upgrading:
Restore Database Backup
Restore your database from the backup taken before migration
Downgrade Package
Pin to the previous version: pip install django-allauth== < previous-versio n >
Reverse Migrations
If you applied new migrations: python manage.py migrate allauth < previous-migratio n >
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
