> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pennersr/django-allauth/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get up and running with django-allauth in minutes

## Overview

This guide will help you configure django-allauth in your Django project and get a working authentication system running quickly.

<Note>
  This guide assumes you have already installed django-allauth. If not, check the [Installation](/installation) guide first.
</Note>

## Configuration Steps

Follow these steps to integrate django-allauth into your Django project:

<Steps>
  <Step title="Configure Template Context Processors">
    Add the required context processor to your `TEMPLATES` setting in `settings.py`:

    ```python settings.py theme={null}
    TEMPLATES = [
        {
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'DIRS': [],
            'APP_DIRS': True,
            'OPTIONS': {
                'context_processors': [
                    # Default Django context processors
                    'django.template.context_processors.debug',
                    'django.contrib.auth.context_processors.auth',
                    'django.contrib.messages.context_processors.messages',
                    
                    # Required by allauth
                    'django.template.context_processors.request',
                ],
            },
        },
    ]
    ```

    <Warning>
      The `django.template.context_processors.request` context processor is required by allauth and must be included.
    </Warning>
  </Step>

  <Step title="Configure Authentication Backends">
    Add the allauth authentication backend to your `settings.py`:

    ```python settings.py theme={null}
    AUTHENTICATION_BACKENDS = [
        # Needed to login by username in Django admin, regardless of `allauth`
        'django.contrib.auth.backends.ModelBackend',

        # `allauth` specific authentication methods, such as login by email
        'allauth.account.auth_backends.AuthenticationBackend',
    ]
    ```

    <Tip>
      Keep the `ModelBackend` to ensure Django admin login continues to work normally.
    </Tip>
  </Step>

  <Step title="Add Apps to INSTALLED_APPS">
    Add the required allauth apps to `INSTALLED_APPS` in your `settings.py`:

    <Tabs>
      <Tab title="Basic Setup">
        For basic account functionality without social authentication:

        ```python settings.py theme={null}
        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',

            # allauth
            'allauth',
            'allauth.account',

            # Your apps
            # ...
        ]

        SITE_ID = 1
        ```
      </Tab>

      <Tab title="With Social Auth">
        For full functionality including social authentication:

        ```python settings.py theme={null}
        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',

            # allauth
            'allauth',
            'allauth.account',
            'allauth.socialaccount',

            # Include the providers you want to enable:
            'allauth.socialaccount.providers.google',
            'allauth.socialaccount.providers.github',
            'allauth.socialaccount.providers.facebook',
            # ... add more providers as needed

            # Your apps
            # ...
        ]

        SITE_ID = 1
        ```
      </Tab>

      <Tab title="With MFA">
        For multi-factor authentication support:

        ```python settings.py theme={null}
        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',

            # allauth
            'allauth',
            'allauth.account',
            'allauth.socialaccount',
            'allauth.mfa',

            # Your apps
            # ...
        ]

        SITE_ID = 1
        ```
      </Tab>
    </Tabs>

    <Note>
      The `django.contrib.sites` framework is required. Make sure to set `SITE_ID = 1` in your settings.
    </Note>
  </Step>

  <Step title="Add Account Middleware">
    Add the account middleware to your `MIDDLEWARE` setting:

    ```python settings.py theme={null}
    MIDDLEWARE = [
        'django.contrib.sessions.middleware.SessionMiddleware',
        'django.middleware.common.CommonMiddleware',
        'django.middleware.csrf.CsrfViewMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.messages.middleware.MessageMiddleware',
        
        # Add the account middleware:
        'allauth.account.middleware.AccountMiddleware',
    ]
    ```

    <Warning>
      The `AccountMiddleware` must be placed after `AuthenticationMiddleware`.
    </Warning>
  </Step>

  <Step title="Configure URL Patterns">
    Add allauth URLs to your project's `urls.py`:

    ```python urls.py theme={null}
    from django.contrib import admin
    from django.urls import path, include

    urlpatterns = [
        path('admin/', admin.site.urls),
        path('accounts/', include('allauth.urls')),
        # Your other URL patterns...
    ]
    ```

    <Tip>
      You can use any URL prefix you prefer instead of `accounts/`. Common alternatives include `auth/` or `user/`.
    </Tip>
  </Step>

  <Step title="Run Migrations">
    Create the necessary database tables:

    ```bash theme={null}
    python manage.py migrate
    ```

    This will create tables for:

    * User accounts
    * Email addresses
    * Email confirmations
    * Social accounts (if enabled)
    * MFA tokens (if enabled)
  </Step>

  <Step title="Configure Basic Settings">
    Add essential allauth configuration to your `settings.py`:

    ```python settings.py theme={null}
    # Authentication settings
    ACCOUNT_AUTHENTICATION_METHOD = 'email'
    ACCOUNT_EMAIL_REQUIRED = True
    ACCOUNT_EMAIL_VERIFICATION = 'mandatory'

    # Signup settings
    ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']

    # Login settings
    LOGIN_REDIRECT_URL = '/'
    ACCOUNT_LOGOUT_REDIRECT_URL = '/'
    ```
  </Step>
</Steps>

## Complete Configuration Example

Here's a complete example of a minimal `settings.py` configuration:

<CodeGroup>
  ```python settings.py (Basic) theme={null}
  import os
  from pathlib import Path

  BASE_DIR = Path(__file__).resolve().parent.parent

  SECRET_KEY = 'your-secret-key-here'
  DEBUG = True
  ALLOWED_HOSTS = ['127.0.0.1', 'localhost']

  INSTALLED_APPS = [
      'django.contrib.admin',
      'django.contrib.auth',
      'django.contrib.contenttypes',
      'django.contrib.sessions',
      'django.contrib.messages',
      'django.contrib.staticfiles',
      'django.contrib.sites',
      
      # allauth
      'allauth',
      'allauth.account',
      'allauth.socialaccount',
  ]

  MIDDLEWARE = [
      'django.contrib.sessions.middleware.SessionMiddleware',
      'django.middleware.common.CommonMiddleware',
      'django.middleware.csrf.CsrfViewMiddleware',
      'django.contrib.auth.middleware.AuthenticationMiddleware',
      'django.contrib.messages.middleware.MessageMiddleware',
      'allauth.account.middleware.AccountMiddleware',
  ]

  ROOT_URLCONF = 'yourproject.urls'

  TEMPLATES = [
      {
          'BACKEND': 'django.template.backends.django.DjangoTemplates',
          'DIRS': [BASE_DIR / 'templates'],
          'APP_DIRS': True,
          'OPTIONS': {
              'context_processors': [
                  'django.template.context_processors.debug',
                  'django.template.context_processors.request',
                  'django.contrib.auth.context_processors.auth',
                  'django.contrib.messages.context_processors.messages',
              ],
          },
      },
  ]

  AUTHENTICATION_BACKENDS = [
      'django.contrib.auth.backends.ModelBackend',
      'allauth.account.auth_backends.AuthenticationBackend',
  ]

  DATABASES = {
      'default': {
          'ENGINE': 'django.db.backends.sqlite3',
          'NAME': BASE_DIR / 'db.sqlite3',
      }
  }

  SITE_ID = 1

  # allauth configuration
  ACCOUNT_AUTHENTICATION_METHOD = 'email'
  ACCOUNT_EMAIL_REQUIRED = True
  ACCOUNT_EMAIL_VERIFICATION = 'mandatory'
  ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']

  LOGIN_REDIRECT_URL = '/'
  ACCOUNT_LOGOUT_REDIRECT_URL = '/'

  # Email backend (for development)
  EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
  ```

  ```python settings.py (Production) theme={null}
  import os
  from pathlib import Path

  BASE_DIR = Path(__file__).resolve().parent.parent

  SECRET_KEY = os.environ.get('SECRET_KEY')
  DEBUG = False
  ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']

  INSTALLED_APPS = [
      'django.contrib.admin',
      'django.contrib.auth',
      'django.contrib.contenttypes',
      'django.contrib.sessions',
      'django.contrib.messages',
      'django.contrib.staticfiles',
      'django.contrib.sites',
      
      # allauth
      'allauth',
      'allauth.account',
      'allauth.socialaccount',
      'allauth.mfa',
      
      # Social providers
      'allauth.socialaccount.providers.google',
      'allauth.socialaccount.providers.github',
  ]

  MIDDLEWARE = [
      '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.security.SecurityMiddleware',
      'allauth.account.middleware.AccountMiddleware',
  ]

  ROOT_URLCONF = 'yourproject.urls'

  TEMPLATES = [
      {
          'BACKEND': 'django.template.backends.django.DjangoTemplates',
          'DIRS': [BASE_DIR / 'templates'],
          'APP_DIRS': True,
          'OPTIONS': {
              'context_processors': [
                  'django.template.context_processors.debug',
                  'django.template.context_processors.request',
                  'django.contrib.auth.context_processors.auth',
                  'django.contrib.messages.context_processors.messages',
              ],
          },
      },
  ]

  AUTHENTICATION_BACKENDS = [
      'django.contrib.auth.backends.ModelBackend',
      'allauth.account.auth_backends.AuthenticationBackend',
  ]

  DATABASES = {
      'default': {
          'ENGINE': 'django.db.backends.postgresql',
          'NAME': os.environ.get('DB_NAME'),
          'USER': os.environ.get('DB_USER'),
          'PASSWORD': os.environ.get('DB_PASSWORD'),
          'HOST': os.environ.get('DB_HOST'),
          'PORT': os.environ.get('DB_PORT', '5432'),
      }
  }

  SITE_ID = 1

  # allauth configuration
  ACCOUNT_AUTHENTICATION_METHOD = 'email'
  ACCOUNT_EMAIL_REQUIRED = True
  ACCOUNT_EMAIL_VERIFICATION = 'mandatory'
  ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']
  ACCOUNT_LOGIN_BY_CODE_ENABLED = True
  ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED = True

  # MFA configuration
  MFA_SUPPORTED_TYPES = ['totp', 'webauthn', 'recovery_codes']
  MFA_PASSKEY_LOGIN_ENABLED = True
  MFA_PASSKEY_SIGNUP_ENABLED = True

  # Security settings
  ACCOUNT_PREVENT_ENUMERATION = True
  ACCOUNT_RATE_LIMITS = {
      'login_failed': '5/5m',
      'signup': '20/d',
  }

  LOGIN_REDIRECT_URL = '/dashboard/'
  ACCOUNT_LOGOUT_REDIRECT_URL = '/'

  # Email configuration
  EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
  EMAIL_HOST = os.environ.get('EMAIL_HOST')
  EMAIL_PORT = int(os.environ.get('EMAIL_PORT', 587))
  EMAIL_USE_TLS = True
  EMAIL_HOST_USER = os.environ.get('EMAIL_HOST_USER')
  EMAIL_HOST_PASSWORD = os.environ.get('EMAIL_HOST_PASSWORD')
  DEFAULT_FROM_EMAIL = os.environ.get('DEFAULT_FROM_EMAIL')
  ```
</CodeGroup>

## Social Provider Configuration

To enable social authentication providers, you need to configure them in your settings:

<CodeGroup>
  ```python Google Provider theme={null}
  SOCIALACCOUNT_PROVIDERS = {
      'google': {
          'SCOPE': [
              'profile',
              'email',
          ],
          'AUTH_PARAMS': {
              'access_type': 'online',
          },
          'APP': {
              'client_id': 'your-google-client-id',
              'secret': 'your-google-client-secret',
              'key': ''
          }
      }
  }
  ```

  ```python GitHub Provider theme={null}
  SOCIALACCOUNT_PROVIDERS = {
      'github': {
          'SCOPE': [
              'user',
              'user:email',
          ],
          'APP': {
              'client_id': 'your-github-client-id',
              'secret': 'your-github-client-secret',
              'key': ''
          }
      }
  }
  ```

  ```python Multiple Providers theme={null}
  SOCIALACCOUNT_PROVIDERS = {
      'google': {
          'APP': {
              'client_id': 'your-google-client-id',
              'secret': 'your-google-client-secret',
          }
      },
      'github': {
          'APP': {
              'client_id': 'your-github-client-id',
              'secret': 'your-github-client-secret',
          }
      },
      'facebook': {
          'METHOD': 'oauth2',
          'APP': {
              'client_id': 'your-facebook-app-id',
              'secret': 'your-facebook-app-secret',
          }
      },
  }
  ```
</CodeGroup>

<Tip>
  Alternatively, you can configure social apps through the Django admin interface instead of settings.
</Tip>

## Testing Your Setup

Start the development server and test your authentication system:

```bash theme={null}
python manage.py runserver
```

Visit the following URLs to verify everything is working:

<CardGroup cols={2}>
  <Card title="Login" icon="right-to-bracket">
    `http://localhost:8000/accounts/login/`
  </Card>

  <Card title="Signup" icon="user-plus">
    `http://localhost:8000/accounts/signup/`
  </Card>

  <Card title="Password Reset" icon="key">
    `http://localhost:8000/accounts/password/reset/`
  </Card>

  <Card title="Admin" icon="user-shield">
    `http://localhost:8000/admin/`
  </Card>
</CardGroup>

## Common Configuration Options

Customize django-allauth behavior with these popular settings:

<AccordionGroup>
  <Accordion title="Login Method Configuration">
    ```python settings.py theme={null}
    # Allow login by email only
    ACCOUNT_AUTHENTICATION_METHOD = 'email'

    # Allow login by username only
    ACCOUNT_AUTHENTICATION_METHOD = 'username'

    # Allow login by either email or username
    ACCOUNT_AUTHENTICATION_METHOD = 'username_email'
    ```
  </Accordion>

  <Accordion title="Email Verification Options">
    ```python settings.py theme={null}
    # Mandatory email verification
    ACCOUNT_EMAIL_VERIFICATION = 'mandatory'

    # Optional email verification (email sent but not required)
    ACCOUNT_EMAIL_VERIFICATION = 'optional'

    # No email verification
    ACCOUNT_EMAIL_VERIFICATION = 'none'
    ```
  </Accordion>

  <Accordion title="Signup Field Configuration">
    ```python settings.py theme={null}
    # Email and password only
    ACCOUNT_SIGNUP_FIELDS = ['email*', 'password1*', 'password2*']

    # Username and password
    ACCOUNT_SIGNUP_FIELDS = ['username*', 'password1*', 'password2*']

    # Username, email, and password
    ACCOUNT_SIGNUP_FIELDS = ['username*', 'email*', 'password1*', 'password2*']

    # Email with confirmation (type twice)
    ACCOUNT_SIGNUP_FIELDS = ['email*', 'email2*', 'password1*']
    ```
  </Accordion>

  <Accordion title="Advanced Features">
    ```python settings.py theme={null}
    # Enable magic link login (login by email code)
    ACCOUNT_LOGIN_BY_CODE_ENABLED = True

    # Enable password reset by code instead of link
    ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED = True

    # Enable email verification by code instead of link
    ACCOUNT_EMAIL_VERIFICATION_BY_CODE_ENABLED = True

    # Prevent account enumeration attacks
    ACCOUNT_PREVENT_ENUMERATION = True

    # Session remember option
    ACCOUNT_SESSION_REMEMBER = None  # Ask user
    # ACCOUNT_SESSION_REMEMBER = True  # Always remember
    # ACCOUNT_SESSION_REMEMBER = False  # Never remember
    ```
  </Accordion>

  <Accordion title="Security Settings">
    ```python settings.py theme={null}
    # Rate limiting (default values shown)
    ACCOUNT_RATE_LIMITS = {
        'login_failed': '5/5m',  # 5 failed attempts per 5 minutes
        'change_password': '5/5m/user',
        'reauthenticate': '10/1h/user',
        'reset_password': '20/1d/ip',
        'reset_password_email': '20/1h/email',
        'signup': '20/1d/ip',
    }

    # Require reauthentication for sensitive operations
    ACCOUNT_REAUTHENTICATION_REQUIRED = True
    ACCOUNT_REAUTHENTICATION_TIMEOUT = 300  # 5 minutes
    ```
  </Accordion>
</AccordionGroup>

## Important Security Considerations

<Warning>
  **Session Engine Compatibility**

  django-allauth is NOT compatible with `SESSION_ENGINE` set to `"django.contrib.sessions.backends.signed_cookies"`.

  Signed cookies are signed but not encrypted, whereas allauth stores secrets (e.g. verification codes) in the session.
</Warning>

<Tip>
  For production environments, always:

  * Use HTTPS
  * Set `DEBUG = False`
  * Configure proper email backend (not console)
  * Enable rate limiting
  * Use strong `SECRET_KEY`
  * Enable account enumeration prevention
</Tip>

## Creating a Superuser

Create an admin user to access the Django admin:

```bash theme={null}
python manage.py createsuperuser
```

You can now:

1. Access the admin at `http://localhost:8000/admin/`
2. Configure social apps
3. Manage user accounts
4. View email addresses and verifications

## URL Patterns Provided

Once configured, django-allauth provides these URL patterns:

| URL Pattern                          | Description                     |
| ------------------------------------ | ------------------------------- |
| `/accounts/login/`                   | User login page                 |
| `/accounts/signup/`                  | User registration page          |
| `/accounts/logout/`                  | Logout endpoint                 |
| `/accounts/password/reset/`          | Password reset request          |
| `/accounts/password/change/`         | Change password (authenticated) |
| `/accounts/email/`                   | Manage email addresses          |
| `/accounts/confirm-email/<key>/`     | Email confirmation              |
| `/accounts/social/connections/`      | Manage social connections       |
| `/accounts/social/login/<provider>/` | Social login initiation         |

<Note>
  You don't need to include `django.contrib.auth.urls` when using allauth, as it provides all necessary authentication URLs.
</Note>

## Example Project

The django-allauth repository includes a fully functional example project:

```bash theme={null}
# Clone the repository
git clone https://codeberg.org/allauth/django-allauth.git
cd django-allauth/examples/regular-django

# Install dependencies
pip install -r requirements.txt

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Run the server
python manage.py runserver
```

Visit the live demo at: [https://django.demo.allauth.org](https://django.demo.allauth.org)

## Next Steps

<CardGroup cols={2}>
  <Card title="Account Configuration" icon="gear" href="https://docs.allauth.org/en/latest/account/configuration.html">
    Explore all available configuration options
  </Card>

  <Card title="Social Providers" icon="share-nodes" href="https://docs.allauth.org/en/latest/socialaccount/providers/index.html">
    Set up social authentication providers
  </Card>

  <Card title="Templates" icon="paintbrush" href="https://docs.allauth.org/en/latest/account/templates.html">
    Customize the look and feel
  </Card>

  <Card title="Signals" icon="tower-broadcast" href="https://docs.allauth.org/en/latest/account/signals.html">
    Hook into authentication events
  </Card>
</CardGroup>