Install & Compatibility
Where this runs
tested against v6.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 94MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.7s · import 0.000s · 94MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
social_django
✓ INSTALLED_APPS = ['social_django']
Required to register the application in Django's settings.
GoogleOAuth2
✓ from social_core.backends.google import GoogleOAuth2
AUTHENTICATION_BACKENDS = ('social_core.backends.google.GoogleOAuth2', ...)
Example of importing a specific social backend for configuration in AUTHENTICATION_BACKENDS.
social_django.urls
✓ from django.urls import include, path
urlpatterns = [path('oauth/', include('social_django.urls', namespace='social'))]
Integrates the social authentication URLs into your project's URL configuration.
SocialAuthExceptionMiddleware
✓ MIDDLEWARE = [..., 'social_django.middleware.SocialAuthExceptionMiddleware']
Optional middleware for handling social authentication exceptions and displaying messages.
This quickstart outlines the essential configuration for integrating Google OAuth2 login into a Django project. It covers adding `social_django` to `INSTALLED_APPS` and `MIDDLEWARE`, configuring authentication backends, defining OAuth2 credentials using environment variables, setting redirect URLs, adding context processors for templates, and including the `social_django` URLs. Remember to run `python manage.py migrate` after configuration.
import os
# settings.py
INSTALLED_APPS = [
# ... existing apps ...
'django.contrib.auth',
'django.contrib.sessions',
'social_django',
]
MIDDLEWARE = [
# ... existing middleware ...
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'social_django.middleware.SocialAuthExceptionMiddleware',
]
AUTHENTICATION_BACKENDS = (
'social_core.backends.google.GoogleOAuth2',
'django.contrib.auth.backends.ModelBackend',
)
SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = os.environ.get('GOOGLE_OAUTH2_KEY', '')
SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET = os.environ.get('GOOGLE_OAUTH2_SECRET', '')
SOCIAL_AUTH_GOOGLE_OAUTH2_SCOPE = ['email', 'profile']
LOGIN_URL = '/login/'
LOGIN_REDIRECT_URL = '/'
LOGOUT_REDIRECT_URL = '/'
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
# ... existing context processors ...
'social_django.context_processors.backends',
'social_django.context_processors.login_redirect',
],
},
},
]
# urls.py
from django.urls import include, path
urlpatterns = [
path('oauth/', include('social_django.urls', namespace='social')),
# ... other paths ...
]
# In your login template (e.g., login.html)
# <a href="{% url 'social:begin' 'google-oauth2' %}">Login with Google</a>
Debug
Known issues
breakingVersion 5.7.0 integrated with `social_core` using a registry instead of monkey patching. While generally an internal change, custom integrations relying on previous monkey-patching behavior might require adjustments. Always review the changelog for details if you have highly customized setups.fixConsult `social-auth-core` and `social-auth-app-django` documentation regarding registry usage if your custom code interacts with internal backend registration mechanisms.
affects: >=5.7.0
breakingSupport for older Django and Python versions has been progressively dropped in recent releases. Version 5.2.0 removed support for Django < 3.2, and 5.5.0 dropped support for additional older Django versions. The library now requires Python >= 3.10 and is compatible with Django versions 4.2, 5.0, 5.1, and 5.2.fixEnsure your project uses Python >= 3.10 and a supported Django version (e.g., 4.2, 5.0, 5.1, 5.2). Refer to the official documentation for the precise list of currently supported versions.
affects: >=5.2.0, >=5.5.0
gotchaA security vulnerability (CVE-2025-61783) in versions prior to 5.6.0 allowed for potentially unsafe account association via email, even if the `associate_by_email` pipeline was not explicitly enabled. Version 5.6.0 fixed this issue, and also introduced a change where storage now filters for active users; you might need to customize `SOCIAL_AUTH_ACTIVE_USERS_FILTER` if your custom user model lacks an `is_active` field.fixUpgrade to `social-auth-app-django` version 5.6.0 or higher. Review and potentially customize `SOCIAL_AUTH_ACTIVE_USERS_FILTER` if using a custom user model without an `is_active` field.
affects: <5.6.0
gotchaA security vulnerability (CVE-2024-32879) in versions prior to 5.4.1 addressed improper handling of case sensitivity with MySQL/MariaDB databases, where the default case-insensitive collation could cause different user IDs to match. This could lead to account spoofing.fixUpgrade to `social-auth-app-django` version 5.4.1 or higher. If using MySQL/MariaDB with an affected version, consider changing the collation of the user ID field as an immediate workaround.
affects: <5.4.1
gotchaSQLite has field length limitations that can cause issues, especially with UIDs from social providers. For production environments, PostgreSQL or MySQL are recommended. If using MySQL InnoDB or SQLite, you might need to add `SOCIAL_AUTH_UID_LENGTH = 223` to your settings to avoid database errors.fixUse PostgreSQL or MySQL for production. For SQLite/MySQL, set `SOCIAL_AUTH_UID_LENGTH = 223` in `settings.py` if encountering UID length errors.
affects: All versions
gotchaThe `SOCIAL_AUTH_PIPELINE` setting, if configured with `social_core.pipeline.social_auth.associate_by_email`, can be insecure. This is because not all social providers validate the user's email address, potentially allowing a malicious user to claim an existing account by registering with a non-validated email on a third-party provider that matches an email in your system.fixOnly enable `associate_by_email` if you are certain that all your configured social providers rigorously validate email addresses. Otherwise, consider alternative association methods or manual verification steps.
affects: All versions
gotchaSensitive credentials (like `SOCIAL_AUTH_GOOGLE_OAUTH2_KEY` and `SOCIAL_AUTH_GOOGLE_OAUTH2_SECRET`) should never be committed to version control. Always use environment variables or a secure configuration management system.fixStore all API keys and secrets in environment variables (e.g., using `os.environ.get`) or a secrets management service, and ensure they are excluded from your repository.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'social_django'
The `social_django` app is either not installed or not included in Django's `INSTALLED_APPS` setting.
fixEnsure `pip install social-auth-app-django` has been run, then add `'social_django'` to your `INSTALLED_APPS` list in `settings.py`.
django.urls.exceptions.NoReverseMatch: Reverse for 'social:begin' not found. 'social' is not a registered namespace.
The `social-auth-app-django` URLs are not included in your project's `urls.py` file with the required `social` namespace.
fixAdd `path('oauth/', include('social_django.urls', namespace='social'))` to your project's `urls.py`. django.core.exceptions.ImproperlyConfigured: The social_django.middleware.SocialAuthExceptionMiddleware requires social_django.context_processors.social_auth to be in TEMPLATES['OPTIONS']['context_processors'].
The `social_django` context processor is missing from the `TEMPLATES` configuration in `settings.py`, which is required by the library's middleware.
fixAdd `'social_django.context_processors.social_auth'` to the `context_processors` list within `TEMPLATES['OPTIONS']` in your `settings.py`.
KeyError: 'SOCIAL_AUTH_GOOGLE_OAUTH2_KEY'
A required API key or secret for a configured social authentication provider (e.g., Google OAuth2) is missing from your `settings.py`.
fixAdd the corresponding `SOCIAL_AUTH_PROVIDER_KEY` and `SOCIAL_AUTH_PROVIDER_SECRET` (e.g., `SOCIAL_AUTH_GOOGLE_OAUTH2_KEY = 'your-key'`) to your `settings.py`.
social_core.exceptions.BackendNotFound: Backend not found
The social authentication backend that the application is trying to use (e.g., `google-oauth2`) is not listed in the `AUTHENTICATION_BACKENDS` setting in `settings.py`.
fixAdd the appropriate backend string (e.g., `'social_core.backends.google.GoogleOAuth2'`) to your `AUTHENTICATION_BACKENDS` list in `settings.py`.
Upgrade
Version history
6.0.1latest on PyPI · released Jul 24, 2026
Audit
Dependencies
social-auth-corerequiredProvides the core social authentication logic and backends.
DjangorequiredThe framework this library integrates with.
setuptoolsoptionalBuild dependency for installation.