Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Custom user model for Django >= 1.5 with the same behaviour as Django's default User but with email instead of username.
branch: master


Django Custom User

Custom user model for Django >= 1.5 with the same behaviour as Django's default User but without a username field. Uses email as the USERNAME_FIELD for authentication.

Quick start

  1. Install django-custom-user with your favorite Python package manager:
pip install django-custom-user
  1. Add 'custom_user' to your INSTALLED_APPS setting:
    # other apps
  1. Set your AUTH_USER_MODEL setting to use EmailUser:
AUTH_USER_MODEL = 'custom_user.EmailUser'
  1. Create the database tables.
python syncdb


Instead of referring to EmailUser directly, you should reference the user model using get_user_model() as explained in the Django documentation. For example:

from django.contrib.auth import get_user_model

user = get_user_model().get(email="")

When you define a foreign key or many-to-many relations to the EmailUser model, you should specify the custom model using the AUTH_USER_MODEL setting. For example:

from django.conf import settings
from django.db import models

class Article(models.Model):
    author = models.ForeignKey(settings.AUTH_USER_MODEL)

Extending EmailUser model

You can easily extend EmailUser by inheriting from AbstractEmailUser. For example:

from custom_user.models import AbstractEmailUser

class MyCustomEmailUser(AbstractEmailUser):
    Example of an EmailUser with a new field date_of_birth
    date_of_birth = models.DateField()

Remember to change the AUTH_USER_MODEL setting to your new class:

AUTH_USER_MODEL = 'my_app.MyCustomEmailUser'

If you use the AdminSite, add the following code to your my_app/ file:

from django.contrib import admin
from custom_user.admin import EmailUserAdmin
from .models import MyCustomEmailUser

class MyCustomEmailUserAdmin(EmailUserAdmin):
    You can customize the interface of your model here.

# Register your models here., MyCustomEmailUserAdmin)


Version 0.5 (2014-09-20)

  • Django 1.7 compatible (thanks to j0hnsmith).
  • Custom application verbose_name in AdminSite with AppConfig.

Version 0.4 (2014-03-06)

  • The create_user() and create_superuser() manager methods now accept is_active and is_staff as parameters (thanks to Edil Kratskih).

Version 0.3 (2014-01-17)

  • AdminSite now works when subclassing AbstractEmailUser (thanks to Ivan Virabyan).
  • Updated model changes from Django 1.6.1.

Version 0.2 (2013-11-24)

  • Django 1.6 compatible (thanks to Simon Luijk).

Version 0.1 (2013-04-09)

  • Initial release.
Something went wrong with that request. Please try again.