Django Custom User Models: Why and How to Implement Them

Why You Should Avoid Django's Default User Model

When starting a new Django project, the default User model seems like a convenient starting point. It provides essential fields like username, password, and email. However, for any application beyond a simple tutorial, this built-in model quickly becomes insufficient. Real-world applications often require additional user attributes such as phone numbers, physical addresses, profile pictures, or dates of birth. Attempting to add these fields to the default model later on, or worse, migrating to a custom model after the project has begun, leads to significant database migration complexities and potential data loss. It’s far more efficient and robust to define your specific user requirements upfront.

Think of it like building a house. You wouldn't start with a basic shack and then decide to add a second story and a garage halfway through construction. You plan the entire structure, including all rooms and features, from the blueprint stage. Similarly, defining your custom user model at the project's inception ensures a solid foundation for your application's authentication and user management system.

Creating Your Custom User Model

Django's flexibility allows you to extend or replace the default user model. The recommended approach involves creating a new model that inherits from AbstractBaseUser or AbstractUser. AbstractUser is suitable if you only need to add a few extra fields to the default user model. If you need a completely different authentication system, AbstractBaseUser offers more control.

Using AbstractUser

To use AbstractUser, you'll create a new app (e.g., accounts) and define your custom user model within its models.py file.

First, ensure your settings.py file points to your custom user model. This is crucial for Django to recognize and use your model instead of the default one. Add the following line to your settings.py:

AUTH_USER_MODEL = 'accounts.CustomUser'

Then, in your accounts/models.py, define your custom user model inheriting from AbstractUser:

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    # add any additional fields
    phone_number = models.CharField(max_length=15, blank=True)
    address = models.CharField(max_length=255, blank=True)
    profile_picture = models.ImageField(upload_to='profile_pics/', blank=True)
    date_of_birth = models.DateField(null=True, blank=True)

    def __str__(self):
        return self.username

After defining your model and updating settings.py, you need to create and apply migrations:

python manage.py makemigrations accounts
python manage.py migrate

This process creates the necessary database tables for your custom user model.

Using AbstractBaseUser

For more advanced customization where you want to define your own fields and authentication logic from scratch, use AbstractBaseUser. This requires you to implement fields like USERNAME_FIELD and methods for user management.

Your settings.py would still point to your custom model:

AUTH_USER_MODEL = 'accounts.CustomUser'

And your accounts/models.py would look something like this:

from django.contrib.auth.models import AbstractBaseUser, BaseUserManager, PermissionsMixin
from django.db import models

class CustomUserManager(BaseUserManager):
    def create_user(self, email, password=None, **extra_fields):
        if not email:
            raise ValueError('Users must have an email')
        user = self.model(email=self.normalize_email(email), **extra_fields)
        user.set_password(password)
        user.save(using=self._db)
        return user

    def create_superuser(self, email, password, **extra_fields):
        user = self.create_user(email, password, **extra_fields)
        user.is_staff = True
        user.is_superuser = True
        user.save(using=self._db)
        return user

class CustomUser(AbstractBaseUser, PermissionsMixin):
    email = models.EmailField(unique=True)
    first_name = models.CharField(max_length=30, blank=True)
    last_name = models.CharField(max_length=30, blank=True)
    is_active = models.BooleanField(default=True)
    is_staff = models.BooleanField(default=False)
    date_joined = models.DateTimeField(auto_now_add=True)

    objects = CustomUserManager()

    USERNAME_FIELD = 'email'
    REQUIRED_FIELDS = ['first_name', 'last_name']

    def __str__(self):
        return self.email

Again, remember to run makemigrations and migrate after these changes.

Managing Custom User Models

Once your custom user model is set up, you need to adjust other parts of your Django project to use it. This includes:

• Admin Site: Register your custom user model with Django's admin site to manage users through the admin interface.
• Forms: Update or create forms (like registration or login forms) to use your custom user model's fields.
• Authentication Views: Ensure your login and logout views correctly handle authentication with your custom user model.

For example, to make your custom user model manageable in the admin, you would create a urls.py in your accounts app and include it in your project's main urls.py. You would also create an admin.py in your accounts app:

# accounts/admin.py
from django.contrib import admin
from django.contrib.auth.admin import UserAdmin
from .models import CustomUser

class CustomUserAdmin(UserAdmin):
    model = CustomUser
    list_display = ('email', 'username', 'first_name', 'last_name', 'is_staff')
    fieldsets = UserAdmin.fieldsets + (
        ('Custom Fields', {'fields': ('phone_number', 'address', 'profile_picture', 'date_of_birth')}),
    )
    add_fieldsets = UserAdmin.add_fieldsets + (
        ('Custom Fields', {'fields': ('phone_number', 'address', 'profile_picture', 'date_of_birth')}),
    )

admin.site.register(CustomUser, CustomUserAdmin)

This ensures that when you add or edit users via the admin panel, your custom fields are available and handled correctly. The choice between AbstractUser and AbstractBaseUser depends entirely on how much you need to deviate from Django's default user structure. For most projects needing a few extra fields, AbstractUser is the simpler and more direct path.

The Unanswered Question: Transitioning Existing Projects

While creating a custom user model from scratch is straightforward, what happens to the thousands of Django projects already using the default User model? The migration path is notoriously complex, often requiring custom data scripts to unpick and re-associate user data. This highlights the importance of making this decision early in the development lifecycle. For developers inheriting a project, understanding the existing user model and the implications of switching is paramount. It's not just about code; it's about preserving user data integrity during a potentially disruptive change.