Use AUTH_USER_MODEL in startproject template

[David D Lowe]

The documentation says:

​https://docs.djangoproject.com/en/1.10/topics/auth/customizing/#using-a-custom-user-model-when-starting-a-project

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. This model behaves identically to the default user model, but you’ll be able to customize it in the future if the need arises:

If you fail to remember to do this when you set up the project, the documentation warns of the difficulty of doing it later:

Changing AUTH_USER_MODEL after you’ve created database tables is significantly more difficult since it affects foreign keys and many-to-many relationships, for example.

This change can’t be done automatically and requires manually fixing your schema, moving your data from the old user table, and possibly manually reapplying some migrations. See #25313 for an outline of the steps.

And it continues, explaining the other difficulties and caveats.

Starting your project with AUTH_USER_MODEL set is highly recommended, and it is a difficult to switch to this method once a project has been created. So why doesn't the default template created by django-admin startproject give a value to AUTH_USER_MODEL by default?

[Tim Graham]

This was proposed in ticket:24370#comment:3, however, it should be discussed on the DevelopersMailingList to ensure there's consensus about it. Feel free to start a thread.

[Tobias Kunze]

Since you need a model to hand to AUTH_USER_MODEL, and this model should be in an app, you can't really populate this setting in startproject, before having run startapp. Adding an app directly on startproject seems like taking the defaults too far, at least to me, so I'm not clear on where this value for AUTH_USER_MODEL is supposed to come in.

[David D Lowe]

I guess the underlying issue is that it is so hard to migrate from not having AUTH_USER_MODEL set to having it set. If it were easier to migrate, then it wouldn't matter what it was set to in the startproject template.

[Timothy Allen]

I've issued a PR that does this and makes the configuration directory named config instead of {{ project_name }} here: ​https://github.com/django/django/pull/15609

These two items have been the most frequent pain points I've run into when teaching newcomers.

[Thibaud Colas]

👋 reading this ticket, and ​https://forum.djangoproject.com/t/django-new-project-structure-name/9987/10, and ​https://groups.google.com/g/django-developers/c/SwFAy8GbhmE – it seems to me like this is only blocked by the decision on the project structure. Other than that blocker, I see lots of approval for:

• A custom user model by default
• It being in a users app
• And there’s been no feedback on Tim’s PR to name said model User in a models.py file (phew).

I thought I’d record this here to note at least what there seems to be consensus on.

[Tim Graham]

This seems obsolete as of #35767, since it's no longer recommended to start a project with a custom user model.