Django Registration

5.2.1 · active · verified Thu Apr 16

Django Registration (django-registration) is an extensible application that provides user registration functionality for Django websites. It supports common registration workflows, including two-step (email activation) and one-step (immediate login), and is designed to work with both Django's default and custom user models. Currently at version 5.2.1, it follows a 'DjangoVer' versioning scheme, ensuring compatibility with supported Django feature releases.

Common errors

```
ModuleNotFoundError: No module named 'django_registration'
```
cause The 'django_registration' app is not listed in `INSTALLED_APPS` in your Django project's settings, or the package was not installed.

fix Ensure `pip install django-registration` was run and add `'django_registration'` to your `INSTALLED_APPS` in `settings.py`.
```
django.core.exceptions.ImproperlyConfigured: ACCOUNT_ACTIVATION_DAYS setting must be specified
```
cause You are using the two-step activation workflow (`django_registration.backends.activation.urls`) but have not defined the `ACCOUNT_ACTIVATION_DAYS` setting.

fix Add `ACCOUNT_ACTIVATION_DAYS = 7` (or your desired number of days) to your `settings.py` file.
```
Your registration form shows no errors when submission fails, just a blank form.
```
cause In your view, if `form.is_valid()` returns `False`, you are likely re-instantiating an empty form instead of rendering the original form which contains the validation errors.

fix Ensure your view passes the form instance that was populated with `request.POST` data to the template when validation fails. Do not create a new `SignUpForm()` after `is_valid()` check: `if request.method == 'POST': form = RegistrationForm(request.POST) if form.is_valid(): ... else: return render(request, 'registration/registration_form.html', {'form': form})`
```
django.db.utils.IntegrityError: UNIQUE constraint failed: auth_user.username
```
cause A user tried to register with a username (or email, if `USERNAME_FIELD` is email) that already exists in the database.

fix This is expected behavior. The user should be informed that the username/email is taken. Ensure your form templates correctly display `form.errors` and specific field errors to the user. `django-registration`'s default forms handle this automatically.

Warnings

breaking Version 5.1.0 significantly refactored `RegistrationForm` (no longer subclassing Django's `UserCreationForm`) and `ActivationView`. While designed for backwards compatibility, projects with highly customized forms or activation logic might require adjustments, especially when interacting with custom user models.
Fix: Review the `RegistrationForm` and `ActivationView` documentation for version 5.1.0+ and test custom registration flows thoroughly. Custom forms might need to be re-evaluated for compatibility with the new base form structure.
breaking Older versions (pre-3.0) dropped Python 2 and Django 1.11 support. The current 5.x series requires Python >=3.9 and supports Django 4.2, 5.0, 5.1, and 5.2. Ensure your Python and Django versions meet these requirements before upgrading `django-registration`.
Fix: Upgrade your Django project to a supported version (e.g., Django 4.2 LTS or 5.x) and ensure your Python environment is 3.9 or higher before installing `django-registration` 5.x.
gotcha For templates to render correctly, `django_registration` (or `registration` in older versions) should be listed *above* `django.contrib.admin` in your `INSTALLED_APPS` setting.
Fix: Adjust `INSTALLED_APPS` order in `settings.py`: `INSTALLED_APPS = ['...', 'django_registration', 'django.contrib.admin', '...']`
gotcha Version 2.1 introduced `ReservedNameValidator`, which prevents registration of certain usernames (e.g., 'admin', 'root'). This validator is applied by default. Similarly, `HTML5EmailValidator` was added in 5.0.0, which is more restrictive for email addresses.
Fix: If you need to allow usernames/email addresses that conflict with these validators, consult the `django-registration` documentation on form customization or disabling specific validators. For example, you can replace the default `RegistrationForm` with a custom one that omits or modifies these validators.

Install

pip install django-registration Install latest version

Imports

RegistrationForm

from django_registration.forms import RegistrationForm

one_step.urls
wrong:
```
from registration.backends.simple import urls
```
correct:
```
from django_registration.backends.one_step import urls as one_step_urls
```
Older versions used 'registration' and 'simple' backend. Current versions use 'django_registration' and specific backend paths like 'one_step'.
activation.urls
wrong:
```
from registration.backends.default import urls
```
correct:
```
from django_registration.backends.activation import urls as activation_urls
```
Older versions used 'registration' and 'default' backend. Current versions use 'django_registration' and specific backend paths like 'activation'.

Quickstart

To quickly set up `django-registration`, add `django_registration` to your `INSTALLED_APPS`. For the two-step activation workflow, define `ACCOUNT_ACTIVATION_DAYS` in your `settings.py`. Then, include the appropriate URL patterns in your project's `urls.py` (e.g., `django_registration.backends.one_step.urls` or `django_registration.backends.activation.urls`), typically under an `/accounts/` prefix, alongside Django's built-in `django.contrib.auth.urls`. Ensure `django.contrib.sites` is also installed and `SITE_ID` is configured.

import os

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',
    'django_registration',
    # 'django_registration.backends.activation', # Optional, explicitly if only using activation backend
    # 'django_registration.backends.one_step', # Optional, explicitly if only using one-step backend
]

SITE_ID = 1 # Required by django.contrib.sites, which django-registration uses.
ACCOUNT_ACTIVATION_DAYS = 7 # Required for the two-step activation workflow.

# Configure email backend for activation (example using console)
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

# Optionally, redirect after login (Django's built-in auth uses this)
LOGIN_REDIRECT_URL = '/'
LOGOUT_REDIRECT_URL = '/'

# urls.py
from django.urls import include, path

urlpatterns = [
    path('admin/', include('admin.site.urls')),
    path('accounts/', include('django_registration.backends.one_step.urls')), # For one-step registration
    path('accounts/', include('django.contrib.auth.urls')), # For login, logout, password reset etc.
]

# Remember to run migrations: python manage.py migrate

view raw JSON →