Custom user models¶
django-registration was first developed, Django’s
authentication system supported only its own built-in user model,
django.contrib.auth.models.User. More recent versions of Django
have introduced support for custom user models.
It is possible to use
django-registration with a custom user
model, so long as certain factors are accounted for.
Using email address as username
If your custom user model treats the email address as a username,
or otherwise does not have distinct email address and username
fields, you must write a custom registration workflow including
custom registration form; the built-in workflows of
django-registration will not function with a user model which
uses the email address as a username.
Writing a custom registration workflow¶
The most straightforward way to guarantee compatibility with a custom
user model is simply to write your own custom registration workflow,
RegistrationForm as necessary. Refer to
the documentation for those classes for notes on how to customize
Using the built-in workflows¶
If you want to use one of the registration workflows built in to
django-registration, there is some accommodation for custom user
models. The two-step model workflow uses a
model with a
OneToOneField to the user model, and uses the
recommended practice of referring to it via the
setting. All built-in workflows also avoid importing or directly
referring to Django’s default user model, instead using the
get_user_model() helper provided in
obtain a reference to whatever model has been specified to represent
However, all of these workflows do make some assumptions about the structure of your user model.
The two-step workflows (both model-based and HMAC-based) require that your user model define the following fields, which are found on Django’s default user model:
EmailFieldholding the user’s email address.
CharFieldholding the user’s password.
BooleanFieldindicating whether the user’s account is active.
You also must specify the attribute
USERNAME_FIELD on your
custom user model to denote the field used as the username, and that
field must accept string values.
Additionally, the model-based workflow requires this field:
DateTimeFieldindicating when the user joined the site.
The model-based and HMAC workflows also require that the user model
define a manager class named
objects, and that this manager class
provide a method
create_user, which will create and return a user
instance from the arguments
django-registration will use that to determine the name of the
password, and require that the user
model provide the
email_user method on instances.
The simple one-step workflow requires
USERNAME_FIELD to be
specified (and for that field to accept strings), requires
password fields, and requires the existence of an
create_user, as in the two-step workflows.
If your custom user model cannot meet these API requirements, your
only option for using
django-registration will be to write your
own registration workflow.
If you wish to write your own subclasses of the forms and views from
the model-based workflow, but will be customizing them to an
incompatible custom user model, also note that you must not add
registration to your
INSTALLED_APPS setting, as doing so would
install the default workflow’s
RegistrationProfile model, which does
make the above-noted assumptions about the structure of your user