Vamos aprender por um exemplo.
\nAtravés deste tutorial, nós vamos caminhar através da criação de uma aplicação básica de enquetes.
\nEla irá consistir de duas partes:
\nUma página pública que permitirá que pessoas vejam as enquetes e votem nelas.
Um site de administração que permite adicionar, alterar e deletar enquetes.
Assumiremos que você já tem o Django instalado. Você pode verificar se o Django está instalado e em qual versão rodando o seguinte comando em um prompt shell (indicado pelo prefixo $):
\nLinux / macOS
$ python -m django --version\nWindows
...\\> py -m django --version\nSe o Django estiver instalado, você verá a versão de sua instalação. Se não estiver, você receberá uma mensagem de erro dizendo “No module named django”.
\nThis tutorial is written for Django 5.1, which supports Python 3.10 and\nlater. If the Django version doesn’t match, you can refer to the tutorial for\nyour version of Django by using the version switcher at the bottom right corner\nof this page, or update Django to the newest version. If you’re using an older\nversion of Python, check Qual versão do Python eu posso usar com Django? to find a compatible\nversion of Django.
\n\nSe esta é a primeira vez em que você está utilizando o Django, você terá que preocupar-se com algumas configurações iniciais. Isto é, você precisará auto-gerar um código para iniciar um projeto Django – uma coleção de configurações para uma instância do Django, incluindo configuração do banco de dados, opções específicas do Django e configurações específicas da aplicação.
\nFrom the command line, cd into a directory where you’d like to store your\ncode and create a new directory named djangotutorial. (This directory name\ndoesn’t matter to Django; you can rename it to anything you like.)
Linux / macOS
$ mkdir djangotutorial\nWindows
...\\> mkdir djangotutorial\nThen, run the following command to bootstrap a new Django project:
\nLinux / macOS
$ django-admin startproject mysite djangotutorial\nWindows
...\\> django-admin startproject mysite djangotutorial\nThis will create a project called mysite inside the djangotutorial\ndirectory. If it didn’t work, see Problemas ao rodar o django-admin.
Veja a estrutura de diretório criada com o comando startproject:
djangotutorial/\n manage.py\n mysite/\n __init__.py\n settings.py\n urls.py\n asgi.py\n wsgi.py\nEsses arquivos são:
\nmanage.py: um utilitário de linha de comando que permite a você interagir com esse projeto Django de várias maneiras. Você pode ler todos os detalhes sobre o manage.py em django-admin and manage.py.
mysite/: A directory that is the actual Python package for your\nproject. Its name is the Python package name you’ll need to use to import\nanything inside it (e.g. mysite.urls).
mysite/__init__.py: um arquivo vazio que diz ao Python que este diretório deve ser considerado um pacote Python. Se você é um iniciante Python, leia mais sobre pacotes na documentação oficial do Python.
mysite/settings.py: configurações para este projeto Django. Configurações do Django irá revelar para você tudo sobre o funcionamento do settings.
mysite/urls.py: as declarações de URLs para este projeto Django; um “índice” de seu site movido a Django. Você pode ler mais sobre URLs em Despachante de URL.
mysite/asgi.py: um ponto de integração para servidores web compatíveis com ASGI usado para servir seu projeto. Veja Como fazer o deploy com ASGI para mais detalhes.
mysite/wsgi.py: um ponto de integração para servidores web compatíveis com WSGI usado para servir seu projeto. Veja Como implementar com WSGI para mais detalhes.
Let’s verify your Django project works. Change into the djangotutorial\ndirectory, if you haven’t already, and run the following commands:
Linux / macOS
$ python manage.py runserver\nWindows
...\\> py manage.py runserver\nVocê verá a seguinte saída na sua linha de comando:
\nPerforming system checks...\n\nSystem check identified no issues (0 silenced).\n\nYou have unapplied migrations; your app may not work properly until they are applied.\nRun 'python manage.py migrate' to apply them.\n\n09 ago. 2026 - 15:50:53\nDjango version 5.1, using settings 'mysite.settings'\nStarting development server at http://127.0.0.1:8000/\nQuit the server with CONTROL-C.\n\n
Agora que o servidor está funcionando, visite http://127.0.0.1:8000/ no seu navegador web. Você verá uma página de “Congratulations!”, com um foguete decolando. Funcionou!
\nVocê iniciou o servidor de desenvolvimento do Django, um servidor web leve escrito exclusivamente em Python. Incluímos isso no Django para que você possa desenvolver coisas rapidamente, sem ter que lidar com a configuração de um servidor de produção – como o Apache – até que esteja pronto para a produção.
\nAgora, uma boa recomendação: não use esse servidor em ambiente de produção. Porque ele foi planejado apenas para desenvolvimento. (Nosso objetivo é criar um framework web e não um servidor web).
\n(To serve the site on a different port, see the runserver reference.)
Agora que seu ambiente – um “projeto” – está configurado, você está pronto para começar o trabalho.
\nCada aplicação que você escreve no Django consiste de um pacote Python que segue uma certa convenção. O Django vem com um utilitário que gera automaticamente a estrutura básica de diretório de uma aplicação, então você pode se concentrar apenas em escrever código em vez de ficar criando diretórios.
\n\nYour apps can live anywhere in your Python path. In\nthis tutorial, we’ll create our poll app inside the djangotutorial folder.
Para criar sua aplicação, certifique-se de que esteja no mesmo diretório que manage.py e digite o seguinte comando:
Linux / macOS
$ python manage.py startapp polls\nWindows
...\\> py manage.py startapp polls\nIsto criará um diretório polls, com a seguinte estrutura:
polls/\n __init__.py\n admin.py\n apps.py\n migrations/\n __init__.py\n models.py\n tests.py\n views.py\nEsta estrutura de diretório irá abrigar a aplicação de enquete.
\nHora de criar a primeira view. Abra o arquivo polls/views.py e ponha o seguinte código em Python dentro dele:
polls/views.pyfrom django.http import HttpResponse\n\n\ndef index(request):\n return HttpResponse("Hello, world. You're at the polls index.")\nThis is the most basic view possible in Django. To access it in a browser, we\nneed to map it to a URL - and for this we need to define a URL configuration,\nor “URLconf” for short. These URL configurations are defined inside each\nDjango app, and they are Python files named urls.py.
To define a URLconf for the polls app, create a file polls/urls.py\nwith the following content:
polls/urls.pyfrom django.urls import path\n\nfrom . import views\n\nurlpatterns = [\n path("", views.index, name="index"),\n]\nYour app directory should now look like:
\npolls/\n __init__.py\n admin.py\n apps.py\n migrations/\n __init__.py\n models.py\n tests.py\n urls.py\n views.py\nThe next step is to configure the global URLconf in the mysite project to\ninclude the URLconf defined in polls.urls. To do this, add an import for\ndjango.urls.include in mysite/urls.py and insert an\ninclude() in the urlpatterns list, so you have:
mysite/urls.pyfrom django.contrib import admin\nfrom django.urls import include, path\n\nurlpatterns = [\n path("polls/", include("polls.urls")),\n path("admin/", admin.site.urls),\n]\nThe path() function expects at least two arguments:\nroute and view.\nThe include() function allows referencing other URLconfs.\nWhenever Django encounters include(), it chops off whatever\npart of the URL matched up to that point and sends the remaining string to the\nincluded URLconf for further processing.
A idéia por trás do include() é facilitar plugar URLs. Uma vez que polls está em sua própria URLconf (polls/urls.py), ele pode ser colocado depois de “/polls/”, ou depois de “/fun_polls/”, u depois de “/content/polls/”, ou qualquer outro início de caminho, e a aplicação ainda irá funcionar
Agora você amarrou uma view index no seu URLconf. Verique se funciona com o seguinte comando:
Linux / macOS
$ python manage.py runserver\nWindows
...\\> py manage.py runserver\nAcesse http://localhost:8000/polls/ no seu navegador, e deverá ver o texto “Hello, world. You’re at the polls index.”, o qual foi definido na view “index”.
\n\nQuando estiver confortável com o básico da sequência de requisição e resposta, leia a parte 2 desse tutorial para começar a trabalhar com banco de dados.
\n