DEV Community

Documendous
Documendous

Posted on

🔐 How to Use Email as the Username in Django (The Right Way)

#django #authentication #modeling #webdev

Using email instead of a username for login is more user-friendly and often preferred in modern applications. Django supports this, but it requires a custom user model. Here's how to set it up cleanly and correctly.

✅ Step 1: Create a Custom User Model

In your core/models.py (or any appropriate app), define a user model using AbstractBaseUser and PermissionsMixin:

from django.contrib.auth.models import ( AbstractBaseUser, BaseUserManager, PermissionsMixin, ) from django.db import models class UserManager(BaseUserManager): def create_user(self, email, password=None, **extra_fields): if not email: raise ValueError("Email is required") email = self.normalize_email(email) user = self.model(email=email, **extra_fields) user.set_password(password) user.save() return user def create_superuser(self, email, password=None, **extra_fields): extra_fields.setdefault("is_staff", True) extra_fields.setdefault("is_superuser", True) return self.create_user(email, password, **extra_fields) class AppUser(AbstractBaseUser, PermissionsMixin): email = models.EmailField(unique=True) full_name = models.CharField(max_length=150) phone_number = models.CharField(max_length=20, blank=True) is_active = models.BooleanField(default=True) is_staff = models.BooleanField(default=False) objects = UserManager() USERNAME_FIELD = "email" REQUIRED_FIELDS = ["full_name"] def __str__(self): return self.email
Enter fullscreen mode Exit fullscreen mode

✅ Step 2: Point Django to Your New User Model

In settings.py:

AUTH_USER_MODEL = "core.AppUser"
Enter fullscreen mode Exit fullscreen mode

Make sure this is set before running any migrations.

✅ Step 3: Create and Apply Migrations 

python manage.py makemigrations core python manage.py migrate
Enter fullscreen mode Exit fullscreen mode

This sets up your database using the email field as the login ID.

✅ Step 4: Use get_user_model() Everywhere

Avoid importing User directly. Use this in views, tests, and signals:

from django.contrib.auth import get_user_model User = get_user_model()
Enter fullscreen mode Exit fullscreen mode

Example usage in tests:

User.objects.create_user(email="user@example.com", password="testpass")
Enter fullscreen mode Exit fullscreen mode

✅ Step 5: Create Superuser with Email

When creating a superuser via script or CLI, use:

python manage.py createsuperuser --email admin@example.com --full_name "Admin"
Enter fullscreen mode Exit fullscreen mode

If you use --noinput, pass in the --email and --full_name values explicitly in your script.

✅ Done

You now have a Django project where email is the unique identifier for login. This setup is clean, minimal, and aligns with real-world authentication flows.

Top comments (0)