Let’s learn by example.
\nThroughout this tutorial, we’ll walk you through the creation of a basic\npoll application.
\nIt’ll consist of two parts:
\nA public site that lets people view polls and vote in them.
An admin site that lets you add, change, and delete polls.
We’ll assume you have Django installed already. You can\ntell Django is installed and which version by running the following command\nin a shell prompt (indicated by the $ prefix):
\nLinux / macOS
$ python -m django --version\nWindows
...\\> py -m django --version\nIf Django is installed, you should see the version of your installation. If it\nisn’t, you’ll get an error telling “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 What Python version can I use with Django? to find a compatible\nversion of Django.
\n\nIf this is your first time using Django, you’ll have to take care of some\ninitial setup. Namely, you’ll need to auto-generate some code that establishes a\nDjango project – a collection of settings for an instance of Django,\nincluding database configuration, Django-specific options and\napplication-specific settings.
\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 Problems running django-admin.
Let’s look at what startproject created:
djangotutorial/\n manage.py\n mysite/\n __init__.py\n settings.py\n urls.py\n asgi.py\n wsgi.py\nThese files are:
\nmanage.py: A command-line utility that lets you interact with this\nDjango project in various ways. You can read all the details about\nmanage.py in 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: An empty file that tells Python that this\ndirectory should be considered a Python package. If you’re a Python beginner,\nread more about packages in the official Python docs.
mysite/settings.py: Settings/configuration for this Django\nproject. Django settings will tell you all about how settings\nwork.
mysite/urls.py: The URL declarations for this Django project; a\n“table of contents” of your Django-powered site. You can read more about\nURLs in URL dispatcher.
mysite/asgi.py: An entry-point for ASGI-compatible web servers to\nserve your project. See How to deploy with ASGI for more details.
mysite/wsgi.py: An entry-point for WSGI-compatible web servers to\nserve your project. See How to deploy with WSGI for more details.
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\nYou’ll see the following output on the command line:
\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\nAug 09, 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
Now that the server’s running, visit http://127.0.0.1:8000/ with your web\nbrowser. You’ll see a “Congratulations!” page, with a rocket taking off.\nIt worked!
\nYou’ve started the Django development server, a lightweight web server written\npurely in Python. We’ve included this with Django so you can develop things\nrapidly, without having to deal with configuring a production server – such as\nApache – until you’re ready for production.
\nNow’s a good time to note: don’t use this server in anything resembling a\nproduction environment. It’s intended only for use while developing. (We’re in\nthe business of making web frameworks, not web servers.)
\n(To serve the site on a different port, see the runserver reference.)
Now that your environment – a “project” – is set up, you’re set to start\ndoing work.
\nEach application you write in Django consists of a Python package that follows\na certain convention. Django comes with a utility that automatically generates\nthe basic directory structure of an app, so you can focus on writing code\nrather than creating directories.
\n\nYour apps can live anywhere in your Python path. In\nthis tutorial, we’ll create our poll app inside the djangotutorial folder.
To create your app, make sure you’re in the same directory as manage.py\nand type this command:
Linux / macOS
$ python manage.py startapp polls\nWindows
...\\> py manage.py startapp polls\nThat’ll create a directory polls, which is laid out like this:
polls/\n __init__.py\n admin.py\n apps.py\n migrations/\n __init__.py\n models.py\n tests.py\n views.py\nThis directory structure will house the poll application.
\nLet’s write the first view. Open the file polls/views.py\nand put the following Python code in it:
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.
The idea behind include() is to make it easy to\nplug-and-play URLs. Since polls are in their own URLconf\n(polls/urls.py), they can be placed under “/polls/”, or under\n“/fun_polls/”, or under “/content/polls/”, or any other path root, and the\napp will still work.
You have now wired an index view into the URLconf. Verify it’s working with\nthe following command:
Linux / macOS
$ python manage.py runserver\nWindows
...\\> py manage.py runserver\nGo to http://localhost:8000/polls/ in your browser, and you should see the\ntext “Hello, world. You’re at the polls index.”, which you defined in the\nindex view.
When you’re comfortable with the basic request and response flow, read\npart 2 of this tutorial to start working with the\ndatabase.
\n