Custom User Model

A custom user model is a model class you define to replace Django's built-in auth.User, registered through the AUTH_USER_MODEL setting, so you can add fields, log in by email, and control how users are created.

Learn Custom User Model in our free Django course — a beginner-friendly interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Django course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

In this lesson you'll compare AbstractUser with AbstractBaseUser, set AUTH_USER_MODEL the right way, switch login from username to email, and write a custom UserManager that powers create_user and create_superuser.

Django gives you two starting points. Subclassing AbstractUser inherits all the standard fields — username, email, password, is_staff, is_active, and the permission relations — so you only add what's new. Subclassing AbstractBaseUser gives you almost nothing but the password machinery, so you define the identifier field, the manager, and the permission mix-in yourself. For most projects, AbstractUser plus a couple of extra fields is the right call.

Here's the simplest possible custom user — just add a field:

Defining the class is not enough — you must tell Django to use it with the AUTH_USER_MODEL setting. This is best done before your first migration , because swapping the user model after foreign keys to it already exist is extremely painful. Always reference settings.AUTH_USER_MODEL in your own foreign keys so your code never hardcodes the user class.

To log in by email with no username, you subclass AbstractBaseUser , make email the unique identifier, set USERNAME_FIELD = "email" , and attach a custom UserManager . The manager's create_user and create_superuser methods enforce the rules: require an email, normalize it, hash the password, and set the staff/superuser flags. This is exactly what createsuperuser calls on the command line.

The AUTH_USER_MODEL setting uses the form "app_label.ModelName" . Replace the blank so the project uses the User model in the accounts app.

❌ I changed AUTH_USER_MODEL after migrating and everything broke

Django can't swap the user model once tables reference it.

✅ Fix: set AUTH_USER_MODEL before the first migration. If you're stuck, the cleanest path is a fresh database during development.

❌ ForeignKey to User causes circular or stale references

You imported the user class directly instead of the setting.

✅ Fix: use settings.AUTH_USER_MODEL in foreign keys and get_user_model() in code.

❌ createsuperuser fails with "Manager isn't available"

Your model has no manager defining create_superuser , or USERNAME_FIELD is wrong.

✅ Fix: attach a UserManager as objects and set USERNAME_FIELD to your login field.

Write a manager with create_user and create_superuser that requires an email, normalizes it, and enforces that a superuser is also staff.

Lesson complete — you own the user model!

You can choose between AbstractUser and AbstractBaseUser, set AUTH_USER_MODEL at project start, switch login from username to email, and write a UserManager whose create_user and create_superuser enforce your rules.

🚀 Up next: Formsets & Inline Formsets — handle many forms at once and edit related objects together.

Practice quiz

• Browse all free courses
• Cheat sheets & quizzes
• Coding dictionary