How to Install django-allauth

django-allauth is the most complete authentication package for Django. It handles registration, login, email verification, password reset, and social authentication in one reusable set of apps.

Installing it involves more than a single pip command. You need to register several apps, add an authentication backend, and include a context processor.

This guide walks through every step. You will install the package, configure your settings, run migrations, and set up your first social provider.

What Is django-allauth?

django-allauth is an integrated set of Django applications that addresses authentication, registration, and account management. It also supports third-party social account authentication.

The package supports over 100 authentication providers, including Google, GitHub, Facebook, and Twitter. It handles OAuth, OAuth2, OpenID Connect, and SAML protocols.

Features include email verification, password reset flows, multi-factor authentication, and account linking. Users can connect multiple social accounts to a single local account.

If you are building APIs with Django REST Framework, django-allauth pairs well with token-based authentication. For guidance on designing secure API endpoints, explore these Django Rest Framework best practices for scalable APIs.

Prerequisites

Before installing django-allauth, verify your environment meets the requirements.

• Python 3.8 or higher installed on your machine
• Django 4.2 or higher in your project
• pip available for package installation
• An active virtual environment is strongly recommended

Activate your virtual environment before installing. This keeps django-allauth isolated from other projects on your system.

If your Django project is not set up yet, make sure you have a working project structure with a settings.py file and a database configured.

Installing django-allauth with pip

The simplest installation provides basic account functionality without social authentication.

 pip install django-allauth 

If you want social authentication support, install the socialaccount extra. This pulls in the additional dependencies for OAuth and OpenID Connect.

 pip install "django-allauth[socialaccount]" 

You can combine multiple extras in one command for a full-featured setup.

 pip install "django-allauth[socialaccount,mfa,saml,headless]" 

Each extra enables a specific feature set. The socialaccount extra adds social providers. The mfa extra enables multi-factor authentication. The saml extra adds SAML 2.0 support. The headless extra provides API endpoints for single-page applications.

Other package managers work too. With Poetry, run poetry add django-allauth[socialaccount]. With Pipenv, run pipenv install "django-allauth[socialaccount]".

Verifying the Installation

After installation, confirm the package is importable. Run this command in your terminal.

 python -c "import allauth; print(allauth.__version__)" 

You should see a version number printed, confirming the package is on your Python path.

 65.14.3 

The exact version may differ. What matters is that the import succeeds without errors.

If you see a "ModuleNotFoundError", pip installed the package for a different interpreter. Use python -m pip install django-allauth to ensure the correct target.

Adding Apps to INSTALLED_APPS

django-allauth requires several apps to be registered. Open your settings.py file and add them to INSTALLED_APPS.

The django.contrib.sites framework is required. django-allauth depends on it for multi-site support and provider configuration.

 # settings.py INSTALLED_APPS = [ # Django built-in apps 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles', 'django.contrib.sites', # Required by allauth # allauth apps 'allauth', 'allauth.account', # Optional: social authentication 'allauth.socialaccount', # Include the providers you want to enable 'allauth.socialaccount.providers.google', 'allauth.socialaccount.providers.github', # Your apps 'myapp', ] SITE_ID = 1 

Only include the social providers you actually plan to use. Each provider adds import overhead and configuration requirements.

For multi-factor authentication, add 'allauth.mfa' to the list. For session management, add 'allauth.usersessions'.

Configuring the Authentication Backend

django-allauth provides its own authentication backend. You must add it to AUTHENTICATION_BACKENDS alongside Django's default backend.

 # settings.py AUTHENTICATION_BACKENDS = [ # Needed to login by username in Django admin 'django.contrib.auth.backends.ModelBackend', # allauth specific authentication methods, such as login by email 'allauth.account.auth_backends.AuthenticationBackend', ] 

Keep the ModelBackend in the list. Without it, Django admin login stops working.

Keep the AuthenticationBackend for allauth's email-based login and social authentication flows.

Adding the Template Context Processor

django-allauth needs access to the request object in templates. Add the request context processor to your TEMPLATES setting.

 # settings.py TEMPLATES = [ { 'BACKEND': 'django.template.backends.django.DjangoTemplates', 'DIRS': [], 'APP_DIRS': True, 'OPTIONS': { 'context_processors': [ 'django.template.context_processors.debug', 'django.template.context_processors.request', # Required by allauth 'django.contrib.auth.context_processors.auth', 'django.contrib.messages.context_processors.messages', ], }, }, ] 

The django.template.context_processors.request processor is mandatory. Without it, allauth templates fail to render with missing context errors.

Adding the Middleware

django-allauth requires its own middleware class. Add it at the end of your MIDDLEWARE setting.

 # settings.py MIDDLEWARE = [ 'django.middleware.security.SecurityMiddleware', 'django.contrib.sessions.middleware.SessionMiddleware', 'django.middleware.common.CommonMiddleware', 'django.middleware.csrf.CsrfViewMiddleware', 'django.contrib.auth.middleware.AuthenticationMiddleware', 'django.contrib.messages.middleware.MessageMiddleware', 'django.middleware.clickjacking.XFrameOptionsMiddleware', 'allauth.account.middleware.AccountMiddleware', # Required ] 

The AccountMiddleware handles account-related request processing. Placing it after the authentication middleware ensures it has access to the authenticated user.

Including allauth URLs

Add the allauth URL patterns to your project's urls.py file. These power the login, signup, and password reset views.

 # urls.py from django.contrib import admin from django.urls import path, include urlpatterns = [ path('admin/', admin.site.urls), path('accounts/', include('allauth.urls')), # allauth URLs ] 

Do not pass a namespace argument to the include function. django-allauth does not support namespacing, and adding one causes a NoReverseMatch error.

The accounts/ prefix is conventional but not required. You can use any prefix that fits your URL structure.

Running Migrations

django-allauth includes database models for social accounts, email addresses, and confirmation tokens. Run migrations to create the required tables.

 python manage.py migrate 

You should see migration output for the allauth apps.

 Operations to perform: Apply all migrations: account, admin, auth, contenttypes, sessions, sites, socialaccount Running migrations: Applying account.0001_initial... OK Applying account.0002_email_max_length... OK Applying socialaccount.0001_initial... OK ... 

If you added the sites framework to INSTALLED_APPS, the migration also creates the default site entry. Confirm that SITE_ID = 1 matches an existing site record.

Setting Up a Social Provider

Social authentication requires provider credentials. You can configure them in settings.py or through the Django admin.

The settings-based approach keeps credentials in environment variables, which is better for version control and deployment pipelines.

 # settings.py SOCIALACCOUNT_PROVIDERS = { 'google': { 'APPS': [ { 'client_id': 'your-google-client-id', 'secret': 'your-google-client-secret', 'key': '', }, ], 'SCOPE': ['profile', 'email'], }, 'github': { 'APPS': [ { 'client_id': 'your-github-client-id', 'secret': 'your-github-secret', 'key': '', }, ], 'SCOPE': ['user'], }, } 

Obtain the client ID and secret from each provider's developer console. Google credentials come from the Google Cloud Console. GitHub credentials come from the GitHub Developer Settings.

Never commit real secrets to your repository. Use environment variables and load them with a library like python-decouple or django-environ.

You can also configure providers through the Django admin at /admin/socialaccount/socialapp/. This stores credentials in the database, which is useful for multi-tenant setups but requires careful database security.

Adding Login Links to Templates

django-allauth provides template tags for rendering provider login links. Load the socialaccount tag library and use the provider_login_url tag.

 {% load socialaccount %} Login with GoogleLogin with GitHub

The provider_login_url tag generates the correct OAuth callback URL for each provider. It handles the redirect flow automatically.

Place these links on your login page or any template where users need to authenticate.

For full control over the authentication flow, you can also use django-allauth with Django REST Framework and GraphQL integration to serve authentication to mobile apps and single-page applications.

Common Installation Problems

Problem: "No module named 'allauth'"

This means the package is not installed for the active Python interpreter. Reinstall with python -m pip install django-allauth to target the correct environment.

Problem: "NoReverseMatch" error on login pages

This usually happens when a namespace argument is passed to the include function. Remove it. The correct pattern is include('allauth.urls') without a namespace.

Problem: "ModuleNotFoundError: No module named 'allauth.account.context_processors'"

This error appears when old context processor paths are listed in your settings. Modern django-allauth versions do not use separate context processor modules. Remove any allauth.account.context_processors entries from your TEMPLATES setting.

Problem: Social provider not showing in admin

If you installed django-allauth without the [socialaccount] extra, the social account module is not available. Reinstall with the extra included.

Problem: Migration conflicts

If you have an existing project with a custom user model, allauth migrations may conflict with your own. Create a new migration for your user app before running allauth migrations.

Problem: Email verification not sending

Development environments rarely have a mail server. Add this setting to print emails to the console instead.

 EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend' 

This prints verification links to your terminal during development. Switch to a real email backend for production.

Verifying the Setup

After configuration, run Django's system check to catch missing settings or misconfigured apps.

 python manage.py check 

A clean run produces this output.

 System check identified no issues (0 silenced). 

Start the development server and navigate to /accounts/login/. You should see the default allauth login page.

If you added social providers, the login page now includes buttons for each configured provider. Test one provider to confirm the OAuth flow works end to end.

Best Practices

Pin your version. Add django-allauth[socialaccount]==65.14.3 to your requirements file for reproducible builds.

Use environment variables for secrets. Never hardcode client IDs or secrets in settings.py.

Keep the ModelBackend. Removing it breaks Django admin login. Always include both authentication backends.

Test your social login flow. OAuth redirects fail silently when URLs are misconfigured. Verify each provider after setup.

Read the release notes before upgrading. django-allauth evolves quickly. Major versions can change settings names and default behavior.

Start with basic authentication. Get email and password login working before adding social providers. A smaller surface area makes debugging easier.

If you plan to deploy soon, review how to deploy a Django app with Fabric to automate the release process. Getting authentication right in development means fewer surprises in production.

Conclusion

Installing django-allauth takes more steps than a typical package. You register multiple apps, add an authentication backend, include a context processor, and configure middleware.

Each step is simple on its own. Together they give you a complete authentication system with registration, login, email verification, password reset, and social login.

Start with the basic installation and get local authentication working. Add social providers one at a time and test each flow. Run the system check after every change.

With django-allauth installed, you have a battle-tested authentication layer that scales from a small project to a production application with thousands of users.