Um modelo de usuário personalizado substitui o User padrão do Django para se adequar às necessidades da sua aplicação — adicionando campos, alterando o identificador de login (por exemplo, email em vez de nome de usuário) ou customizando o comportamento. O conselho crítico e frequentemente repetido: configure um modelo de usuário personalizado no próprio início do projeto, mesmo que você não precise de mudanças agora, porque alterá-lo depois é extremamente difícil.
The default User has fixed fields (username, email, first/last name) and uses
USERNAME as the login field. Real apps often need:
✓ Email-based login (no username)
✓ Extra fields (phone, avatar, role, preferences) on the user itself
✓ Custom authentication behavior
⚠️ Changing the user model AFTER migrations exist is VERY hard — the User model is
referenced by auth, admin, sessions, foreign keys throughout the database.
Swapping it later requires complex, risky data migrations.
→ ALWAYS define a custom user model at project START (before the first migration),
even an empty one, so you can extend it freely later. Django's docs strongly
recommend this for EVERY new project.
Esta é a lição prática fundamental: custa quase nada configurar um modelo de usuário personalizado no primeiro dia, mas adaptar um a um projeto estabelecido é uma tarefa complexa e propensa a erros — então você faz isso desde o início como um seguro.
# models.py — add fields, keep Django's auth behavior
from django.contrib.auth.models import AbstractUser
class User(AbstractUser):
phone = models.CharField(max_length=20, blank=True)
avatar = models.ImageField(upload_to="avatars/", blank=True)
is_premium = models.BooleanField(default=False)
# settings.py — tell Django to use it
AUTH_USER_MODEL = "myapp.User"
AbstractUser mantém todos os campos padrão do Django e a maquinaria de autenticação — você apenas adiciona campos. A abordagem mais simples e comum.
from django.contrib.auth.models import AbstractBaseUser, BaseUserManager, PermissionsMixin
class User(AbstractBaseUser, PermissionsMixin):
email = models.EmailField(unique=True)
USERNAME_FIELD = "email" # log in with EMAIL instead of username
REQUIRED_FIELDS = []
objects = CustomUserManager() # a manager defining create_user/create_superuser
AbstractBaseUser oferece controle total sobre o modelo de usuário (por exemplo, removendo o nome de usuário completamente para login apenas por email) — mais trabalho, mas máxima flexibilidade.
from django.conf import settings
from django.contrib.auth import get_user_model
# in models — reference via settings.AUTH_USER_MODEL
author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
# in code — get the active user model dynamically
User = get_user_model() # NOT a direct import of the default User
Sempre referencie o modelo de usuário via settings.AUTH_USER_MODEL (em modelos) e get_user_model() (em código), nunca importando o User padrão diretamente — para que seu código funcione com o modelo personalizado.
Usar um modelo de usuário personalizado é um conhecimento importante com uma lição prática crítica e frequentemente enfatizada que todo desenvolvedor Django deve internalizuar: configure-o no próprio início de cada projeto.
A razão pela qual isso é tão importante é a assimetria severa na dificuldade — definir um modelo de usuário personalizado no primeiro dia (mesmo uma subclasse AbstractUser vazia) custa quase nada e oferece flexibilidade inestimável, enquanto mudar para um modelo de usuário personalizado depois que o projeto tem migrações e dados é extremamente difícil e arriscado, porque o modelo User é profundamente referenciado em todo o Django (autenticação, admin, sessões) e por chaves estrangeiras em todo o seu banco de dados, exigindo migrações de dados complexas e propensas a erros para mudar.
Esta é a razão pela qual a própria documentação do Django recomenda fortemente um modelo de usuário personalizado para cada novo projeto, independentemente de necessidade imediata — é um seguro contra um pesadelo de migração futuro.
Além deste conselho crítico de timing, entender como criar modelos de usuário personalizados — AbstractUser para simplesmente adicionar campos mantendo o comportamento de autenticação do Django (o caso comum e fácil), e AbstractBaseUser para controle total como login baseado em email (removendo o nome de usuário completamente) — é valioso para atender aos requisitos de aplicações reais (campos de usuário extras, identificadores de login alternativos, autenticação customizada).
Igualmente importante é saber referenciar o modelo de usuário corretamente (via settings.AUTH_USER_MODEL e get_user_model(), nunca uma importação direta) para que o código funcione com qualquer modelo de usuário configurado.
Porque quase toda aplicação real tem necessidades específicas do usuário além dos padrões do Django (e até aquelas que não têm se beneficiam da flexibilidade), e porque o custo de não configurar isso cedo é tão alto, entender modelos de usuário personalizados — especialmente o imperativo de estabelecer um no início do projeto — é um conhecimento prático e crítico que previne um erro comum e sério no nível do projeto, tornando-o uma peça frequentemente citada da sabedoria de boas práticas do Django.