Se você está começando com Django, cedo ou tarde bate a confusão:
“Eu criei a view, mas o site não abre.”
Na prática, o problema quase sempre está no urls.py.
Testei isso dezenas de vezes em projetos reais, e o padrão se repete.
Pense no urls.py como o mapa do seu site.
Sem ele, o Django não sabe qual código executar para cada endereço.
O que é o urls.py na prática
O urls.py é o arquivo que liga três coisas:
-
Uma URL
-
Uma view
-
Um nome de rota
Quando alguém acessa:
O Django faz exatamente isso:
-
Lê o
urls.py -
Procura uma rota
/blog/ -
Executa a view associada
Sem esse arquivo bem configurado, nada aparece.
Estrutura básica de um urls.py
Vamos desmontar um urls.py real, sem pressa.
Importando o path
Aqui não tem mistério:
-
path()é a função que cria URLs -
Toda rota no Django usa
path()
Se você não importou isso, o arquivo nem funciona.
Importando as views
Cada view é uma página.
Na prática:
-
HomeView→ página inicial -
BlogListView→ lista de posts -
PostDetailView→ detalhe de um post -
CategoryPostListView→ posts por categoria
Esse foi o comportamento que observei em projetos reais.
Uma view = uma responsabilidade clara.
O app_name: pequeno detalhe, grande dor de cabeça
Esse detalhe evita bugs difíceis de rastrear.
Ele serve para:
-
Evitar conflito entre apps
-
Usar
reverse()no backend -
Usar
{% url %}no template
Exemplo real no template:
👉 blog: vem direto do app_name.
Na prática, quando você esquece isso, os templates quebram sem avisar claramente.
O coração do arquivo: urlpatterns
Aqui mora tudo que importa.
Essa lista contém todas as rotas do app.
Cada item conecta:
👉 URL → View → Nome
Se não está nessa lista, o Django ignora.
Analisando cada rota com calma
Página inicial
Explicação direta:
-
""→ URL vazia →/ -
HomeView.as_view()→ view baseada em classe -
name="home"→ nome da rota
Acesso final:
Erro comum aqui: esquecer o as_view().
Lista de posts do blog
Aqui já fica mais claro:
-
URL:
/blog/ -
View: lista todos os posts
-
Nome da rota:
post_list
Acesso:
Esse padrão é o mais usado em projetos de conteúdo.
Detalhe de post (URL dinâmica)
Aqui entra um conceito crítico.
O que é <slug:slug>?
É um parâmetro dinâmico.
Exemplo real de URL:
O valor como-aprender-django:
-
Vai para a view
-
A view usa isso para buscar o post certo no banco
Na prática, o Django faz:
Depois disso, a view resolve o resto.
Posts por categoria
Exemplo de acesso:
Comportamento esperado:
-
Recebe o slug
python -
Filtra os posts daquela categoria
-
Retorna a lista correta
Esse padrão funciona muito bem para SEO e navegação.
Visualizando o fluxo mentalmente
Uma forma simples de guardar isso:
E no urls.py:
Sempre nessa ordem.
Sempre com esses três elementos.
Erros comuns de iniciantes (e como evitar)
Esses erros aparecem direto em suporte e projetos reais:
Esquecer a barra / no final da URL
Errar o nome da view importada
Não usar .as_view() em Class Based Views
Não definir app_name
Confundir slug com id
Na prática, 80% dos bugs de rota vêm daqui.
Como eu valido se meu urls.py está correto
Sempre sigo esse checklist:
-
A URL abre no navegador?
-
O nome da rota funciona no
{% url %}? -
A view está sendo chamada?
-
O slug chega corretamente na view?
Se tudo isso passa, o urls.py está sólido.
Em resumo
O urls.py não é só configuração.
Ele é o sistema nervoso do seu projeto Django.
Quando você entende:
-
path() -
app_name -
URLs dinâmicas
-
Relação entre URL e view
Você para de “brigar” com o framework.
E na prática, passa a resolver bugs muito mais rápido.
FAQ – Perguntas Frequentes sobre urls.py no Django
O que é o arquivo urls.py no Django?
O urls.py é o arquivo responsável por mapear as URLs do site para as views. Ele define qual código será executado quando o usuário acessa um determinado endereço. Sem ele, o Django não sabe o que mostrar.
Qual a função do path()?
A função path() cria uma rota. Ela conecta três elementos: a URL, a view e o nome da rota. Toda URL no Django precisa ser definida usando path() ou re_path().
Por que usar app_name no urls.py?
O app_name evita conflitos entre apps diferentes. Além disso, ele permite usar URLs nomeadas com segurança em templates e no backend, utilizando {% url %} e reverse().
O que significa usar as_view()?
O método as_view() é obrigatório em Class Based Views. Ele transforma a classe em uma função que o Django consegue executar. Sem isso, ocorre erro ao acessar a rota.
O que é um slug em uma URL?
Um slug é um texto amigável usado na URL. Geralmente representa o título de um conteúdo, como um post ou categoria. Exemplo: /posts/como-aprender-django/.
Qual a diferença entre slug e id?
O id é numérico e interno do banco de dados. O slug é legível, melhor para SEO e experiência do usuário. Na maioria dos blogs e sites de conteúdo, o slug é a melhor escolha.
Por que minha URL não abre no navegador?
Na prática, os motivos mais comuns são:
- Esquecer a barra
/no final da URL - Nome da view digitado errado
- Esquecer o
as_view() - Rota não registrada em
urlpatterns
Preciso reiniciar o servidor após alterar o urls.py?
Normalmente não. O servidor de desenvolvimento do Django detecta mudanças automaticamente. No entanto, se algo estranho acontecer, reiniciar pode ajudar.
Posso ter vários urls.py no projeto?
Sim. Cada app pode ter seu próprio urls.py. Depois, você inclui essas rotas no urls.py principal do projeto usando include().
Se você está começando com Django e quer entender o framework como um todo, recomendo ler primeiro o artigo completo sobre o que é Django e para que ele serve . Ele te dá a base necessária para não se perder na estrutura do projeto.
Depois disso, o próximo passo natural é dominar os models. Na prática, muitos erros em URLs e views acontecem por falta de entendimento do banco de dados. Por isso, vale muito a pena estudar este guia: models.py: guia completo para entender e usar corretamente .
