Django users take for granted the ability to configure your own user model but prior to Django 1.5 you were stuck with Django’s predefined User model. If you want to take advantage of this new functionality then keep on reading as I’ll go through how to migrate your current application to the new configurable user model.

Getting Started

For the sake of simplicity let’s make our own User object that is exactly the same as Django’s current but fixes the email max_length field to comply with RFC 5321 of 254 characters and adds a required field for the user’s twitter handle.

# myapp.models.py from django.contrib.auth.models import AbstractBaseUser class MyUser(AbstractBaseUser): username = models.CharField(max_length=40, unique=True, db_index=True) email = models.EmailField(max_length=254, unique=True) twitter_handle = models.CharField(max_length=255) ... USERNAME_FIELD = 'email' REQUIRED_FIELDS = ['twitter_handle']

You’ll notice a few new things about this:

Inheriting AbstractBaseUser:

This adds a few helper fields such as password and last_login as well as methods for setting the user’s password, getting the username, checking if the user is active. You can check out a full list of what it includes here.

USERNAME_FIELD:

This is a string describing the name of the field on the User model that is used as the unique identifier. This will usually be a username of some kind, but it can also be an email address or any other unique identifier.

REQUIRED_FIELDS:

A list of the field names that must be provided when creating a user. REQUIRED_FIELDS must contain all required fields on your User model, but should not contain the USERNAME_FIELD .

Now that you’ve created your User model you have to tell Django that you want to use it instead of their default User model. To do this you add the following to your settings file:

# settings.py AUTH_USER_MODEL = 'myapp.MyUser'

With this setting Django now knows which User model to use.

Using Foreign Keys

Once you’ve set up your model it’s now time reference it in other models.

from django.conf import settings from django.db import models class Post(models.Model): author = models.ForeignKey(settings.AUTH_USER_MODEL)

This tells Django to create a ForeignKey to the User model that you specify in your settings.

Custom Manager

Now that you’ve created your own User model you also need to create your own Manager to handle the creation of Users and Super Users. If your User model defines the same fields as Django’s default User you can just install Django’s UserManager.

from django.contrib.auth.models import UserManager, AbstractBaseUser class MyUser(AbstractBaseUser): ... objects = UserManager

If your User model includes different fields you’ll need to define your own custom manager that extends BaseUserManager.

from django.contrib.auth.models import BaseUserManager, AbstractBaseUser class MyUserManager(BaseUserManager): def create_user(self, email, twitter_handle, password=None): if not email: raise ValueError('Users must have an email address') user = self.model( email=MyUserManager.normalize_email(email), twitter_handle=twitter_handle, ) user.set_password(password) user.save(using=self._db) return user def create_superuser(self, email, twitter_handle, password): user = self.create_user(email, password=password, twitter_handle=twitter_handle ) user.is_admin = True user.save(using=self._db) return user class MyUser(AbstractBaseUser): ... objects = MyUserManager

Other Methods

There are a few other methods you need to include:

get_full_name:

A longer formal identifier for the user. A common interpretation would be the full name of the user, but it can be any string that identifies the user.

get_short_name:

A short, informal identifier for the user. A common interpretation would be the first name of the user, but it can be any string that identifies the user in an informal way.

is_active:

A boolean attribute that indicates whether the user is considered “active”. This attribute is provided as an attribute on AbstractBaseUser defaulting to True.

Final Example