Custom user model with AbstractUser in Django - Deep Dive

Overview - Custom user model with AbstractUser

What is it?

A custom user model with AbstractUser in Django is a way to create your own user class by extending Django's built-in AbstractUser class. This lets you add extra fields or change behavior while keeping all the default user features. It is useful when the default user model does not fit your application's needs. This approach keeps compatibility with Django's authentication system.

Why it matters

Without customizing the user model early, you might face big problems later if you need extra user information or different login methods. Changing the user model after starting a project is very hard and error-prone. Custom user models let you design your user data exactly how your app needs it, making your app more flexible and future-proof.

Where it fits

Before learning this, you should understand Django basics, models, and the default User model. After this, you can learn about custom user managers, authentication backends, and user permissions to build full user systems.

Mental Model

Core Idea

Extending AbstractUser lets you build a user model tailored to your app by adding fields and methods while keeping Django's built-in user features intact.

Think of it like...

It's like customizing a car by starting with a standard model and adding your own features, instead of building a car from scratch or using a plain one that doesn't fit your needs.

┌─────────────────────────────┐
│       AbstractUser          │
│  (built-in Django user)     │
│  - username                │
│  - password                │
│  - email                   │
│  - first_name              │
│  - last_name               │
└─────────────┬───────────────┘
              │ extends
              ▼
┌─────────────────────────────┐
│     CustomUserModel          │
│  - all AbstractUser fields   │
│  - extra fields (e.g., phone)│
│  - custom methods           │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Django's Default User

Concept: Learn what the default User model provides and why it might be limited.

Django comes with a built-in User model that has basic fields like username, password, email, first and last name. It supports authentication and permissions out of the box. However, it does not include fields like phone number or profile picture. If your app needs more user info, the default model is not enough.

Result

You know the default User model's fields and limitations.

Understanding the default User model helps you see why customizing it is often necessary for real apps.

2

Foundation

What is AbstractUser in Django?

Concept: AbstractUser is a base class you can extend to create your own user model with default fields included.

AbstractUser is a Django class that has all the fields and methods of the default User model but is designed to be extended. Unlike the default User, AbstractUser is abstract, meaning it doesn't create a database table by itself. You create your own user model by inheriting from AbstractUser and adding fields or methods.

Result

You understand AbstractUser as a customizable base user class.

Knowing AbstractUser lets you customize users without losing built-in features.

3

Intermediate

Creating a Custom User Model by Extending AbstractUser

🤔Before reading on: Do you think you can add new fields directly to AbstractUser or must you create a new class? Commit to your answer.

Concept: You create a new user model class that inherits from AbstractUser and add your extra fields there.

To customize, define a new class in your app's models.py that inherits from AbstractUser. Add any new fields you want, like phone_number or birth_date. For example: from django.contrib.auth.models import AbstractUser from django.db import models class CustomUser(AbstractUser): phone_number = models.CharField(max_length=15, blank=True) Then update your settings.py to use this model: AUTH_USER_MODEL = 'yourapp.CustomUser'

Result

You have a new user model with default and custom fields.

Creating a subclass of AbstractUser is the cleanest way to extend user data while keeping Django's auth features.

4

Intermediate

Updating Settings and Migrations for Custom User

🤔Before reading on: Should AUTH_USER_MODEL be set before or after running initial migrations? Commit to your answer.

Concept: You must tell Django to use your custom user model before creating database tables.

In settings.py, set AUTH_USER_MODEL to your custom user model before running migrations. This ensures Django creates the correct tables. If you change AUTH_USER_MODEL after migrations, you get errors. Then run: python manage.py makemigrations python manage.py migrate This creates the database schema for your custom user.

Result

Django uses your custom user model in the database and authentication.

Setting AUTH_USER_MODEL early avoids complex migration problems later.

5

Intermediate

Using Custom User Model in Admin and Forms

🤔Before reading on: Do you think the default UserAdmin works automatically with your custom user? Commit to your answer.

Concept: You need to customize Django admin and forms to work with your new user model fields.

Django's admin uses UserAdmin for the default User. For your custom user, you must create a new admin class inheriting from UserAdmin and register it. You also update fieldsets to include new fields. Example: from django.contrib import admin from django.contrib.auth.admin import UserAdmin from .models import CustomUser class CustomUserAdmin(UserAdmin): fieldsets = UserAdmin.fieldsets + ( ("Extra Info", {"fields": ("phone_number",)}), ) admin.site.register(CustomUser, CustomUserAdmin) Similarly, update forms if you use custom user creation or change forms.

Result

Your custom user fields appear and can be edited in Django admin.

Admin customization is necessary to manage new user fields easily.

6

Advanced

Handling Authentication and User Creation

🤔Before reading on: Will Django's default user creation forms work with your custom user model? Commit to your answer.

Concept: You often need custom user creation and change forms to handle new fields and validation.

Django's default UserCreationForm and UserChangeForm expect the default User model. For a custom user, create new forms inheriting from these and update Meta to use your model. Add fields and validation as needed. Use these forms in admin or your views to create and update users properly.

Result

User creation and update handle your custom fields correctly.

Custom forms ensure your new user fields are properly handled during signup and editing.

7

Expert

Common Pitfalls and Best Practices in Custom User Models

🤔Before reading on: Can you change AUTH_USER_MODEL after initial migrations without issues? Commit to your answer.

Concept: Changing user model mid-project causes complex errors; plan your user model early and follow best practices.

Once you run migrations with a user model, changing AUTH_USER_MODEL is very difficult and can break your database and auth system. Always define your custom user model before the first migration. Use AbstractUser to keep compatibility. Avoid adding too many unrelated fields; consider profile models if needed. Test authentication flows thoroughly.

Result

You avoid migration errors and maintain a stable user system.

Knowing these pitfalls saves time and prevents hard-to-debug errors in production.

Under the Hood

AbstractUser is an abstract Django model that defines fields and methods for user authentication, permissions, and profile data. When you extend it, Django creates a concrete database table for your custom user model including inherited and new fields. Django's authentication system uses the AUTH_USER_MODEL setting to know which model to use for login, permissions, and sessions. Forms and admin classes rely on this model to provide user management features.

Why designed this way?

Django provides AbstractUser to allow developers to customize user data without rewriting authentication logic. It separates the user data structure from authentication mechanisms. This design avoids duplicating code and supports flexibility. Alternatives like AbstractBaseUser require more work but offer full control. AbstractUser balances ease and customization.

┌─────────────────────────────┐
│       AbstractUser          │
│  (abstract base model)      │
│  - username                │
│  - password                │
│  - email                   │
│  - permissions             │
└─────────────┬───────────────┘
              │ inherited by
              ▼
┌─────────────────────────────┐
│     CustomUserModel          │
│  - all AbstractUser fields   │
│  - extra fields             │
└─────────────┬───────────────┘
              │ used by
              ▼
┌─────────────────────────────┐
│  Django Authentication      │
│  - login/logout             │
│  - permissions checks      │
│  - sessions                 │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Can you safely change AUTH_USER_MODEL after running migrations? Commit yes or no.

Common Belief: You can change AUTH_USER_MODEL anytime without problems.

Reality: Changing AUTH_USER_MODEL after migrations causes database conflicts and breaks authentication.

Why it matters: Ignoring this leads to complex errors and often requires resetting the database, losing data.

Quick: Does extending AbstractUser mean you must rewrite all authentication logic? Commit yes or no.

Common Belief: Extending AbstractUser requires rewriting login and permission code.

Reality: Extending AbstractUser keeps all built-in authentication and permission logic intact.

Why it matters: This misconception scares beginners away from customizing users, limiting app flexibility.

Quick: Does adding fields to AbstractUser automatically show them in Django admin? Commit yes or no.

Common Belief: New fields on custom user appear in admin without extra setup.

Reality: You must customize UserAdmin to display new fields in admin interface.

Why it matters: Without this, admins cannot edit or see new user data, causing confusion.

Quick: Is AbstractUser the only way to customize users in Django? Commit yes or no.

Common Belief: AbstractUser is the only way to customize user models.

Reality: You can also use AbstractBaseUser for full control, but it requires more work.

Why it matters: Knowing alternatives helps choose the right approach for your app's complexity.

Expert Zone

1

Custom user models must be defined before the first migration to avoid complex database issues.

2

Extending AbstractUser preserves compatibility with third-party Django apps expecting the default user model structure.

3

Custom user managers often need to be implemented alongside custom user models to handle user creation properly.

When NOT to use

If you need full control over authentication fields and behavior, use AbstractBaseUser instead of AbstractUser. For simple extra user info, consider a separate profile model linked by OneToOneField to the default User to avoid complexity.

Production Patterns

In production, teams define custom user models early, add only necessary fields, customize admin and forms, and write tests for authentication flows. They also implement custom user managers for creating users and superusers consistently.

Connections

Object-Oriented Programming Inheritance

Custom user models extend AbstractUser using class inheritance.

Understanding inheritance helps grasp how custom user models reuse and extend existing user features.

Database Schema Migration

Custom user models require migrations to update database schema.

Knowing migrations clarifies why changing user models mid-project is difficult and how to manage schema changes safely.

Identity and Access Management (IAM) in Security

Custom user models are part of managing user identities and permissions.

Understanding IAM principles helps design user models that support secure authentication and authorization.

Common Pitfalls

#1 Changing AUTH_USER_MODEL after initial migrations.

Wrong approach:

In settings.py:
AUTH_USER_MODEL = 'myapp.NewUser'

# After running initial migrations with default User

python manage.py migrate

Correct approach:

Define AUTH_USER_MODEL = 'myapp.NewUser' in settings.py before any migrations.

Then run:
python manage.py makemigrations
python manage.py migrate

Root cause:

Django creates database tables for the user model during initial migrations; changing the model later causes conflicts.

#2 Not customizing admin to show new user fields.

Wrong approach:

admin.site.register(CustomUser)

# No custom UserAdmin class to include new fields

Correct approach:

from django.contrib.auth.admin import UserAdmin

class CustomUserAdmin(UserAdmin):
fieldsets = UserAdmin.fieldsets + (("Extra Info", {"fields": ("phone_number",)}),)

admin.site.register(CustomUser, CustomUserAdmin)

Root cause:

Django admin uses UserAdmin which doesn't know about new fields unless explicitly told.

#3 Using default UserCreationForm with custom user model.

Wrong approach:

from django.contrib.auth.forms import UserCreationForm

# Using UserCreationForm without changes for CustomUser

Correct approach:

from django.contrib.auth.forms import UserCreationForm

class CustomUserCreationForm(UserCreationForm):
class Meta:
model = CustomUser
fields = ('username', 'phone_number', 'email')

Root cause:

Default forms expect the default User model and do not handle extra fields.

Key Takeaways

Custom user models with AbstractUser let you add fields while keeping Django's built-in user features.

Set AUTH_USER_MODEL before running migrations to avoid database conflicts.

Customize admin and forms to handle new user fields properly.

Changing user models mid-project is very difficult; plan your user model early.

Understanding inheritance and migrations is key to mastering custom user models.