Custom User Model

Why the Default Model is Limiting

Django's default User model is a one-size-fits-all solution that assumes every user has a username, password, and email. While this works for simple projects, real-world applications often require tracking additional metadata like phone numbers, birth dates, or specific account types. Because the User model is deeply integrated into Django's authentication system, changing it later requires a manual migration strategy that can be incredibly difficult to manage once production data exists. By default, Django uses a model that forces the 'username' field for identification, which is an outdated practice for modern web applications where users identify by email addresses. Starting with a custom model gives you complete control over the underlying database table structure and validation logic. Understanding that the User model is just another database table, we realize we must define it before any migrations are created to ensure Django properly links all related foreign keys to our new class.

# settings.py
# You must declare this early to tell Django to use your model
AUTH_USER_MODEL = 'accounts.CustomUser'

Implementing AbstractBaseUser

To build a custom model, we inherit from 'AbstractBaseUser'. Unlike the basic 'User' model, 'AbstractBaseUser' provides only the absolute core of the authentication system, such as password hashing and token management. It does not provide fields like usernames or email addresses by default; you must define exactly which fields you want. This approach follows the principle of composition over inheritance. By manually adding your fields, you ensure that the database schema is clean and tailored exactly to your business requirements. You are also responsible for defining the 'USERNAME_FIELD', which identifies which specific field acts as the unique identifier for authentication. This design pattern ensures that your application is not carrying unnecessary 'baggage' from the default implementation. It requires developers to be explicit, which reduces bugs and unexpected behavior when the application grows in complexity. This is the foundation upon which you add your domain-specific user requirements.

from django.contrib.auth.models import AbstractBaseUser

class CustomUser(AbstractBaseUser):
    # The field used for login
    email = models.EmailField(unique=True)
    is_active = models.BooleanField(default=True)
    
    USERNAME_FIELD = 'email' # Replaces 'username'

Creating the Required Manager

Django's authentication system relies heavily on a 'UserManager' to handle the logic of object creation, such as setting passwords and validating unique constraints. When you create a custom user, the default manager will fail because it expects the standard username-based fields. You must create a custom 'BaseUserManager' class that implements 'create_user' and 'create_superuser' methods. This manager acts as the entry point for Django's commands and admin forms. By overriding these methods, you define the business logic for what constitutes a valid user during the signup process. For instance, if you require a phone number or a specific company ID during user creation, you inject that logic here. This ensures that every user created through your application—or through the command line—adheres to the exact same validation rules and initialization requirements, preventing dirty data from entering your database at the source of creation.

from django.contrib.auth.models import BaseUserManager

class UserManager(BaseUserManager):
    def create_user(self, email, password=None):
        # Logic to normalize and save the user
        user = self.model(email=self.normalize_email(email))
        user.set_password(password)
        user.save(using=self._db)
        return user

Adding Permissions and Admin Compatibility

To make a custom user model fully compatible with Django's admin interface and permission system, it must implement a few specific methods and fields. Specifically, 'PermissionsMixin' should be inherited. This mixin adds the necessary fields and methods, such as 'is_superuser' and 'groups', to interact with Django's existing permission checking system. Without this, your custom model would have no way to track which users are administrators or what access level they have to individual models. It is a vital step because it bridges the gap between your custom user object and the broad array of built-in features Django provides for security. The methods 'has_perm' and 'has_module_perms' are also provided by this mixin, allowing the admin dashboard to verify if a user has access to specific parts of the system. This integration allows you to maintain full functionality without reinventing the authentication logic from scratch.

from django.contrib.auth.models import PermissionsMixin

class CustomUser(AbstractBaseUser, PermissionsMixin):
    # Now supports groups and permissions
    is_staff = models.BooleanField(default=False)

Registering the Custom User

Finally, after defining the model and the manager, you must link them together in your application settings. Django needs to know that your project is using a different model than the one it provides internally. This is done by pointing the 'AUTH_USER_MODEL' variable in your settings file to your new class. It is imperative that this is completed before running your first migration. If you try to switch models after your database has already been initialized with the default User table, you will encounter serious schema migration errors that require database intervention to fix. By declaring it early, Django's ORM generates the initial database schema correctly, with all foreign keys pointing to your 'CustomUser' table. This ensures that whenever you reference the 'User' model in other parts of your code, Django dynamically resolves it to your custom implementation, maintaining consistency across your entire project architecture.

# settings.py
# This tells the entire framework to use your class
AUTH_USER_MODEL = 'accounts.CustomUser'

Interview questions

All Django interview questions →

Check yourself

Take the full Django quiz →