Introduction to Custom User Models

A custom user model is like designing your own membership card instead of using the generic one Django hands out by default.

In this page:

Why Use a Custom User Model
Pointing Django at the Custom Model
Referencing the User Model Safely

Why Use a Custom User Model

Django recommends starting new projects with a custom user model, even a minimal one, since swapping it in later requires much more work.

Warning: Switching AUTH_USER_MODEL after migrations already exist for the default User is difficult and risky.

Example: Why Use a Custom User Model

AbstractUser already includes username, email, password, and permissions — this only adds one extra field on top.

markup

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

class CustomUser(AbstractUser):
    date_of_birth = models.DateField(null=True, blank=True)

{# Django-only code -- models.py/views.py/urls.py/settings.py snippets, or template markup using Django template tags/variables -- can't run standalone via Judge0 or the browser preview, since it needs a real Django project. Only this course's pure-Python examples (example_lang == 'python', no Django imports) are actually runnable, so those still get the button below. #}

Pointing Django at the Custom Model

AUTH_USER_MODEL tells Django which model to use for authentication instead of the built-in User.

Note: Set this before running your first migrate — changing it afterward requires a full database reset.

Example: Pointing Django at the Custom Model

'accounts.CustomUser' means the CustomUser model lives inside an app named accounts.

markup

AUTH_USER_MODEL = 'accounts.CustomUser'

Referencing the User Model Safely

get_user_model() always returns whichever model AUTH_USER_MODEL points to, so code keeps working even if the user model changes later.

Example: Referencing the User Model Safely

This code works whether AUTH_USER_MODEL points to the default User or to CustomUser, without any changes.

markup

from django.contrib.auth import get_user_model

User = get_user_model()
new_user = User.objects.create_user(username='carol', password='Pass1234')

Common Mistakes

Switching to a custom user model after already running migrations on the default User — Django strongly recommends setting AUTH_USER_MODEL before the first migrate.
Forgetting to update AUTH_USER_MODEL in settings.py after creating the custom model, so Django keeps using the default User.
Subclassing models.Model instead of AbstractUser, losing all the built-in auth fields and behavior for free.

Chapter Summary

AbstractUser extends Django's default User with extra fields while keeping all existing behavior.
AUTH_USER_MODEL in settings.py must point to the custom model, ideally set before the first migration.
get_user_model() should be used in code instead of importing User directly, so it works with any user model.

🔒

Chapter Quiz — Complete all 12 topics to unlock

0/12 topics done

Complete these topics first:

← Previous Lesson Session Authentication Basics Next Lesson → Sending Emails with Django

Introduction to Custom User Models

Why Use a Custom User Model

Pointing Django at the Custom Model

Referencing the User Model Safely

Chapter Quiz — Complete all 12 topics to unlock

Login to run this code