Fixing Django FieldError at /admin/accounts/customuser/add/

If you are a Django developer who wants to add a custom user model to your project, you've likely come across this error on Django versions 5.0 and above.

FieldError at /admin/accounts/customuser/add/
Unknown field(s) (usable_password) specified for CustomUser. Check fields/fieldsets/exclude attributes of class CustomUserAdmin.

The issue is around UserCreationForm. In Django versions up to 4.2, you could set your accounts/forms.py file to add updated user creation and change forms.

# accounts/forms.py
from django.contrib.auth.forms import UserCreationForm, UserChangeForm

from .models import CustomUser

class CustomUserCreationForm(UserCreationForm):

    class Meta:
        model = CustomUser
        fields = ("username", "email")

class CustomUserChangeForm(UserChangeForm):

    class Meta:
        model = CustomUser
        fields = ("username", "email")

However, as of Django 5.0, that leads to the above-mentioned FieldError. The fix is straightforward to do, thankfully, which is to swap out UserCreationForm for the newer AdminUserCreationForm instead, which includes the additional usable_password field causing the initial issue.

# accounts/forms.py
from django.contrib.auth.forms import AdminUserCreationForm, UserChangeForm  # new

from .models import CustomUser


class CustomUserCreationForm(AdminUserCreationForm):  # new

    class Meta:
        model = CustomUser
        fields = ("username", "email")


class CustomUserChangeForm(UserChangeForm):

    class Meta:
        model = CustomUser
        fields = ("username", "email")

You can see the related ticket #35678 and forum discussion.

For a complete guide on using a custom user model in Django, refer to this tutorial.