Fix "AUTH_USER_MODEL Refers to Model That Has Not Been Installed"

Problem statement

Django refuses to start:

django.core.exceptions.ImproperlyConfigured: AUTH_USER_MODEL refers to model
'accounts.User' that has not been installed

AUTH_USER_MODEL = "accounts.User" tells Django which model represents users. During startup, django.contrib.auth looks it up in the app registry. If there is no app labelled accounts, or that app has no model called User, or the lookup happens before the app is loaded, you get this error.

1. Use the format "app_label.ModelName", for example "accounts.User", not "accounts.models.User".
2. Add the app to INSTALLED_APPS in every settings module that sets AUTH_USER_MODEL.
3. Check the label: an app at apps.accounts has the label accounts unless its AppConfig says otherwise.
4. Make sure models.py actually defines the model and imports cleanly.
5. Do not import get_user_model() results at module level in apps that load before accounts.

Step-by-step solution

1. Check the setting format

# correct
AUTH_USER_MODEL = "accounts.User"

# wrong
AUTH_USER_MODEL = "accounts.models.User"
AUTH_USER_MODEL = "apps.accounts.User"

The value has exactly one dot: the app label, then the model class name.

2. Confirm the app is installed and its label

python manage.py shell -c "from django.apps import apps; c = apps.get_app_config('accounts'); print(c.name, [m.__name__ for m in c.get_models()])"

If this raises LookupError, the app is missing from INSTALLED_APPS in the settings this process uses, or it has a different label. Production settings that redefine INSTALLED_APPS instead of extending base.py are a common culprit.

3. Make sure the model imports

If accounts/models.py raises an exception on import, for example an import of a package that is not installed on the server, the app loads without models. Run it directly with production settings:

DJANGO_SETTINGS_MODULE=config.settings.production python -c "import django; django.setup(); import accounts.models"

A traceback here is the real error.

4. Reference the user model lazily

In other apps, refer to users through the setting, not by importing the class at module level:

from django.conf import settings
from django.db import models

class Order(models.Model):
    customer = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT)

Calling get_user_model() at import time in a module loaded early can trigger the error, because the accounts app may not be ready yet. Call it inside functions instead.

5. Switching to a custom user model on an existing project

Changing AUTH_USER_MODEL after the first migrate is a different, harder problem. Existing migrations reference auth.User, and the new setting without matching migrations leads to errors such as InconsistentMigrationHistory or this one. The supported path:

1. Create a custom model that copies auth.User's fields and uses db_table = "auth_user".
2. Fake its initial migration on existing databases.
3. Point AUTH_USER_MODEL at it.
4. Later, rename the table and add fields with normal migrations.

Rehearse it on a copy of production first. New projects should start with a custom user model on day one.

Explanation

AUTH_USER_MODEL is a swappable setting. Django, the admin, and every third-party app that has a foreign key to users resolve it through the app registry when models load. The error is raised by django.contrib.auth.get_user_model() when that resolution fails. Because the auth app loads early and many packages reference the user model, the failure surfaces at startup regardless of which code actually made the bad reference.

Edge cases / notes

• Third-party migrations. Packages that were migrated before you swapped the user model have foreign keys to auth_user. Their migrations use settings.AUTH_USER_MODEL, but the database columns already point at the old table.
• Tests. Test settings that override INSTALLED_APPS must keep the user model's app.
• Abstract base. Inheriting from AbstractUser is fine; the concrete model must still live in an installed app.

Next steps

• For general label problems, see Fix Django LookupError: No Installed App With Label.
• If migration history no longer matches after the switch, read Fix Django InconsistentMigrationHistory.
• Review user model changes with the Django Migration Review Checklist.

FAQ

What format does AUTH_USER_MODEL use?

"app_label.ModelName", with a single dot, such as "accounts.User".

Can I change AUTH_USER_MODEL after going live?

Yes, but it requires a careful migration that reuses the existing table. It is not a settings-only change.

Why does it work locally but not on the server?

The server probably loads a different settings module whose INSTALLED_APPS lacks the app, or models.py fails to import because of a missing dependency.

Should every project use a custom user model?

Django's documentation recommends it for new projects, because adding one later is much harder.