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):
\n$ python -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 1.11 and Python 3.4 or later. If the\nDjango version doesn’t match, you can refer to the tutorial for your version\nof Django by using the version switcher at the bottom right corner of this\npage, or update Django to the newest version. If you are still using Python\n2.7, you will need to adjust the code samples slightly, as described in\ncomments.
\nSee How to install Django for advice on how to remove\nolder versions of Django and install a newer one.
\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, then run the following command:
$ django-admin startproject mysite\nThis will create a mysite directory in your current directory. If it didn’t\nwork, see Problems running django-admin.
Let’s look at what startproject created:
mysite/\n manage.py\n mysite/\n __init__.py\n settings.py\n urls.py\n wsgi.py\nThese files are:
\nThe outer mysite/ root directory is just a container for your\nproject. Its name doesn’t matter to Django; you can rename it to anything\nyou like.
manage.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.
The inner mysite/ directory 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/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 outer mysite directory, if\nyou haven’t already, and run the following commands:
$ python 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 1.11, using settings 'mysite.settings'\nStarting development server at http://127.0.0.1:8000/\nQuit the server with CONTROL-C.\n\n
You’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.)
\nNow that the server’s running, visit http://127.0.0.1:8000/ with your Web\nbrowser. You’ll see a “Welcome to Django” page, in pleasant, light-blue pastel.\nIt worked!
\n\n\nNow 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 on your Python path. In\nthis tutorial, we’ll create our poll app right next to your manage.py\nfile so that it can be imported as its own top-level module, rather than a\nsubmodule of mysite.
To create your app, make sure you’re in the same directory as manage.py\nand type this command:
$ python 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 simplest view possible in Django. To call the view, we need to map\nit to a URL - and for this we need a URLconf.
\nTo create a URLconf in the polls directory, create a file called urls.py.\nYour app directory should now look like:
polls/\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\nIn the polls/urls.py file include the following code:
polls/urls.pyfrom django.conf.urls import url\n\nfrom . import views\n\nurlpatterns = [\n url(r'^$', views.index, name='index'),\n]\nThe next step is to point the root URLconf at the polls.urls module. In\nmysite/urls.py, add an import for django.conf.urls.include and insert\nan include() in the urlpatterns list, so you have:
mysite/urls.pyfrom django.conf.urls import include, url\nfrom django.contrib import admin\n\nurlpatterns = [\n url(r'^polls/', include('polls.urls')),\n url(r'^admin/', admin.site.urls),\n]\nThe include() function allows referencing other\nURLconfs. Note that the regular expressions for the\ninclude() function doesn’t have a $ (end-of-string\nmatch character) but rather a trailing slash. Whenever Django encounters\ninclude(), it chops off whatever part of the URL\nmatched up to that point and sends the remaining string to the included URLconf\nfor 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. Lets verify it’s\nworking, run the following command:
$ python 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.
The url() function is passed four arguments, two\nrequired: regex and view, and two optional: kwargs, and name.\nAt this point, it’s worth reviewing what these arguments are for.
url() argument: regexLink to this heading#The term “regex” is a commonly used short form meaning “regular expression”,\nwhich is a syntax for matching patterns in strings, or in this case, url\npatterns. Django starts at the first regular expression and makes its way down\nthe list, comparing the requested URL against each regular expression until it\nfinds one that matches.
\nNote that these regular expressions do not search GET and POST parameters, or\nthe domain name. For example, in a request to\nhttps://www.example.com/myapp/, the URLconf will look for myapp/. In a\nrequest to https://www.example.com/myapp/?page=3, the URLconf will also\nlook for myapp/.
If you need help with regular expressions, see Wikipedia’s entry and the\ndocumentation of the re module. Also, the O’Reilly book “Mastering\nRegular Expressions” by Jeffrey Friedl is fantastic. In practice, however,\nyou don’t need to be an expert on regular expressions, as you really only need\nto know how to capture simple patterns. In fact, complex regexes can have poor\nlookup performance, so you probably shouldn’t rely on the full power of regexes.
Finally, a performance note: these regular expressions are compiled the first\ntime the URLconf module is loaded. They’re super fast (as long as the lookups\naren’t too complex as noted above).
\nurl() argument: viewLink to this heading#When Django finds a regular expression match, Django calls the specified view\nfunction, with an HttpRequest object as the first\nargument and any “captured” values from the regular expression as other\narguments. If the regex uses simple captures, values are passed as positional\narguments; if it uses named captures, values are passed as keyword arguments.\nWe’ll give an example of this in a bit.
url() argument: kwargsLink to this heading#Arbitrary keyword arguments can be passed in a dictionary to the target view. We\naren’t going to use this feature of Django in the tutorial.
\nurl() argument: nameLink to this heading#Naming your URL lets you refer to it unambiguously from elsewhere in Django,\nespecially from within templates. This powerful feature allows you to make\nglobal changes to the URL patterns of your project while only touching a single\nfile.
\nWhen you’re comfortable with the basic request and response flow, read\npart 2 of this tutorial to start working with the\ndatabase.
\n