Documentation unclear on custom user models

[Matthew Somerville]

At ​https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#using-a-custom-user-model-when-starting-a-project it says "If you’re starting a new project, it’s highly recommended to set up a custom user model, even if the default User model is sufficient for you." and shows a subclass of AbstractUser as a starting example.

Yet a few sections down at ​https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#specifying-a-custom-user-model it says "When you start your project with a custom user model, stop to consider if this is the right choice for your project." and then recommends inheriting from AbstractBaseUser. - But the docs told me it's highly recommended as the right choice :)

Then further down again at ​https://docs.djangoproject.com/en/3.2/topics/auth/customizing/#extending-django-s-default-user it says "If you’re entirely happy with Django’s User model, but you want to add some additional profile information, you could subclass django.contrib.auth.models.AbstractUser and add your custom profile fields, although we’d recommend a separate model as described in the “Model design considerations” note of Specifying a custom user model." - but in the first section you specifically gave an example of subclassing AbstractUser, so how can it now not be recommended in the same document.

Recommending the AbstractUser subclass comes from #24370 and the second part comes from toning down the message, in #20629. After reading this for a new project, I am quite confused. I made a start at trying to tidy it up, but I wasn't sure what would actually come first and what it should say where, so decided to open this ticket instead.

[Carlton Gibson]

Hi Matthew — thanks for the report.

I have to say we need to go back to the DevelopersMailingList for this. There are as many opinions as there are developers: ranging from "use the default model, or you end up using your auth model as a random data bin" to "we should update the default template to create the subclass, so users don't find this advise until too late" to ... — if we could agress the canonical advice then a rewrite might be on the cards.

Thanks.

[Ashley]

+1, I was reading these docs today, got confused by the emphasis to create a customer user model immediately followed by cautionary advice. I'm relatively new to Django but from the few seemingly reputable opinions I've encountered, it seems if anyone expecting any sort of growth, or even an inkling of an eventual need to make User more versatile (even if uncertain immediately), one should simply make the call from the start, utilize a custom user model. The main reason I hear is the pain encountered with a move after initial migrations. I'd imagine for newcomers, it might be less painful to go for a customer user model than to have to deal with a custom migration to such a model shortly thereafter.

​https://docs.djangoproject.com/en/4.1/topics/auth/customizing/

... If you’re starting a new project, it’s highly recommended to set up a custom user model. ...
... When you start your project with a custom user model, stop to consider if this is the right choice for your project. ...