Why and how should you use a custom user model?

Question

Accepted Answer

A **custom user model** replaces Django's default `User` to fit your application's needs — adding fields, changing the login identifier (e.g. email instead of username), or customizing behavior. The critical, oft-repeated advice: set up a custom user model **at the very start** of a project, even if you don't need changes yet, because changing it later is extremely painful.

## Why: the default User is limited and hard to change later

```text
The default User has fixed fields (username, email, first/last name) and uses
USERNAME as the login field. Real apps often need:
  ✓ Email-based login (no username)
  ✓ Extra fields (phone, avatar, role, preferences) on the user itself
  ✓ Custom authentication behavior
```

## The critical reason to do it FIRST

```text
⚠️ Changing the user model AFTER migrations exist is VERY hard — the User model is
   referenced by auth, admin, sessions, foreign keys throughout the database.
   Swapping it later requires complex, risky data migrations.
→ ALWAYS define a custom user model at project START (before the first migration),
   even an empty one, so you can extend it freely later. Django's docs strongly
   recommend this for EVERY new project.
```

This is the key practical lesson: it costs almost nothing to set up a custom user model on day one, but retrofitting one onto an established project is a major, error-prone undertaking — so you do it upfront as insurance.

## How: extending AbstractUser (the easy way)

```python
# models.py — add fields, keep Django's auth behavior
from django.contrib.auth.models import AbstractUser

class User(AbstractUser):
    phone = models.CharField(max_length=20, blank=True)
    avatar = models.ImageField(upload_to="avatars/", blank=True)
    is_premium = models.BooleanField(default=False)
```

```python
# settings.py — tell Django to use it
AUTH_USER_MODEL = "myapp.User"
```

`AbstractUser` keeps all of Django's default fields and auth machinery — you just add fields. The simplest, most common approach.

## How: AbstractBaseUser (full control, e.g. email login)

```python
from django.contrib.auth.models import AbstractBaseUser, BaseUserManager, PermissionsMixin

class User(AbstractBaseUser, PermissionsMixin):
    email = models.EmailField(unique=True)
    USERNAME_FIELD = "email"          # log in with EMAIL instead of username
    REQUIRED_FIELDS = []
    objects = CustomUserManager()     # a manager defining create_user/create_superuser
```

`AbstractBaseUser` gives full control over the user model (e.g. removing username entirely for email-only login) — more work, but maximum flexibility.

## Referencing the user model correctly

```python
from django.conf import settings
from django.contrib.auth import get_user_model

# in models — reference via settings.AUTH_USER_MODEL
author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)

# in code — get the active user model dynamically
User = get_user_model()              # NOT a direct import of the default User
```

Always reference the user model via `settings.AUTH_USER_MODEL` (in models) and `get_user_model()` (in code), never by importing the default `User` directly — so your code works with the custom model.

## Why it matters

Using a custom user model is important knowledge with a critical, frequently-emphasized practical lesson that every Django developer should internalize: **set it up at the very start of every project**.

The reason this matters so much is the severe asymmetry in difficulty — defining a custom user model on day one (even an empty `AbstractUser` subclass) costs almost nothing and provides invaluable flexibility, while switching to a custom user model *after* the project has migrations and data is extremely painful and risky, because the User model is deeply referenced throughout Django (authentication, admin, sessions) and by foreign keys across your entire database, requiring complex, error-prone data migrations to change.

This is why Django's own documentation strongly recommends a custom user model for every new project, regardless of immediate need — it's insurance against a future migration nightmare.

Beyond this critical timing advice, understanding *how* to create custom user models — **`AbstractUser`** for simply adding fields while keeping Django's auth behavior (the common, easy case), and **`AbstractBaseUser`** for full control like email-based login (removing username entirely) — is valuable for meeting real application requirements (extra user fields, alternative login identifiers, custom auth).

Equally important is knowing to **reference the user model correctly** (via `settings.AUTH_USER_MODEL` and `get_user_model()`, never a direct import) so code works with whatever user model is configured.

Because nearly every real application has user-specific needs beyond Django's defaults (and even those that don't benefit from the flexibility), and because the cost of not setting this up early is so high, understanding custom user models — especially the imperative to establish one at project start — is important, practically-critical knowledge that prevents a common and serious project-level mistake, making it a frequently-cited piece of Django best-practice wisdom.