# Custom user models

When `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.

Warning

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, subclassing `RegistrationView`, `ActivationView`, and `RegistrationForm` as necessary. Refer to the documentation for those classes for notes on how to customize them.

## 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 `AUTH_USER_MODEL` 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 `django.contrib.auth` to obtain a reference to whatever model has been specified to represent users.

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:

- `email` – a `CharField` or `EmailField` holding the user’s email address. This field is required by `RegistrationForm`.
- `password` – a `CharField` holding the user’s password.
- `is_active` – a `BooleanField` indicating 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:

- `date_joined` – a `DateField` or `DateTimeField` indicating 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 `USERNAME_FIELD` (`django-registration` will use that to determine the name of the username field) `email`, and `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 `email` and `password` fields, and requires the existence of an `objects` manager defining `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 model.