We are going to create a poll application which is similar to the one in the Django Docs. Django is very high level and most of the things come out of the box.
Installation
We assume you have python installed already.Python will come with pip which is pythons package manager, similar to composer for PHP. To install Django globally run the command below
$ python -m pip install Django $ python -m django --version
Create Project
If this is your first time using Django, you’ll have to take care of some initial setup. Namely, you’ll need to auto-generate some code that establishes a Django project – a collection of settings for an instance of Django, including database configuration, Django-specific options and application-specific settings.
From the command line, cd
into a directory where you’d like to store your code, then run the following command:/
$ django-admin startproject mysite
So your project will be your overall website project and you can have mulitple apps (discussed later) within a project.
Folder Tree
mysite/ manage.py mysite/ __init__.py settings.py urls.py asgi.py wsgi.py
These files are:
- The outer
mysite/
root directory is a container for your project. Its name doesn’t matter to Django; you can rename it to anything you like. manage.py
: A command-line utility that lets you interact with this Django project in various ways. You can read all the details aboutmanage.py
in django-admin and manage.py.- The inner
mysite/
directory is the actual Python package for your project. Its name is the Python package name you’ll need to use to import anything inside it (e.g.mysite.urls
). mysite/__init__.py
: An empty file that tells Python that this directory should be considered a Python package. If you’re a Python beginner, read more about packages in the official Python docs.mysite/settings.py
: Settings/configuration for this Django project. Django settings will tell you all about how settings work.mysite/urls.py
: The URL declarations for this Django project; a “table of contents” of your Django-powered site. You can read more about URLs in URL dispatcher.mysite/asgi.py
: An entry-point for ASGI-compatible web servers to serve your project. See How to deploy with ASGI for more details.mysite/wsgi.py
: An entry-point for WSGI-compatible web servers to serve your project. See How to deploy with WSGI for more details.
Start Server
/
$ python manage.py runserver


Database setup¶
Now, open up mysite/settings.py
. It’s a normal Python module with module-level variables representing Django settings.
By default, the configuration uses SQLite. If you’re new to databases, or you’re just interested in trying Django, this is the easiest choice. SQLite is included in Python, so you won’t need to install anything else to support your database. When starting your first real project, however, you may want to use a more scalable database like PostgreSQL, to avoid database-switching headaches down the road.
If you wish to use another database, install the appropriate database bindings and change the following keys in the DATABASES
'default'
item to match your database connection settings:
ENGINE
– Either'django.db.backends.sqlite3'
,'django.db.backends.postgresql'
,'django.db.backends.mysql'
, or'django.db.backends.oracle'
. Other backends are also available.NAME
– The name of your database. If you’re using SQLite, the database will be a file on your computer; in that case,NAME
should be the full absolute path, including filename, of that file. The default value,BASE_DIR / 'db.sqlite3'
, will store the file in your project directory.
If you are not using SQLite as your database, additional settings such as USER
, PASSWORD
, and HOST
must be added. For more details, see the reference documentation for DATABASES
.
Some of these applications make use of at least one database table, though, so we need to create the tables in the database before we can use them. To do that, run the following command:/
$ python manage.py migrate
Creating models¶
Now we’ll define your models – essentially, your database layout, with additional metadata.
In our poll app, we’ll create two models: Question
and Choice
. A Question
has a question and a publication date. A Choice
has two fields: the text of the choice and a vote tally. Each Choice
is associated with a Question
.
polls/models.py¶
from django.db import models # Create your models here. class Question(models.Model): question_text = models.CharField(max_length=200) pub_date = models.DateTimeField('date published') def __str__(self): return self.question_text class Choice(models.Model): question = models.ForeignKey(Question, on_delete=models.CASCADE) choice_text = models.CharField(max_length=200) votes = models.IntegerField(default=0) def __str__(self): return self.choice_text
Here, each model is represented by a class that subclasses django.db.models.Model
. Each model has a number of class variables, each of which represents a database field in the model.
Each field is represented by an instance of a Field
class – e.g., CharField
for character fields and DateTimeField
for datetimes. This tells Django what type of data each field holds.
The name of each Field
instance (e.g. question_text
or pub_date
) is the field’s name, in machine-friendly format. You’ll use this value in your Python code, and your database will use it as the column name.
You can use an optional first positional argument to a Field
to designate a human-readable name. That’s used in a couple of introspective parts of Django, and it doubles as documentation. If this field isn’t provided, Django will use the machine-readable name. In this example, we’ve only defined a human-readable name for Question.pub_date
. For all other fields in this model, the field’s machine-readable name will suffice as its human-readable name.
Some Field
classes have required arguments. CharField
, for example, requires that you give it a max_length
. That’s used not only in the database schema, but in validation, as we’ll soon see.
A Field
can also have various optional arguments; in this case, we’ve set the default
value of votes
to 0.
Finally, note a relationship is defined, using ForeignKey
. That tells Django each Choice
is related to a single Question
. Django supports all the common database relationships: many-to-one, many-to-many, and one-to-one.
Activating models
To include the app in our project, we need to add a reference to its configuration class in the INSTALLED_APPS
setting. The PollsConfig
class is in the polls/apps.py
file, so its dotted path is 'polls.apps.PollsConfig'
. Edit the mysite/settings.py
file and add that dotted path to the INSTALLED_APPS
setting. It’ll look like this:

Now Django knows to include the polls
app. Let’s run another command:
$ python manage.py makemigrations polls
By running makemigrations
, you’re telling Django that you’ve made some changes to your models (in this case, you’ve made new ones) and that you’d like the changes to be stored as a migration.
$ python manage.py sqlmigrate polls 0001
Introducing the Django Admin
Creating an admin user¶
First we’ll need to create a user who can login to the admin site. Run the following command:/
$ python manage.py createsuperuser
Fill in prompts
go to the the URL http://127.0.0.1:8000/admin/
Make the poll app modifiable in the admin¶
But where’s our poll app? It’s not displayed on the admin index page.
Only one more thing to do: we need to tell the admin that Question
objects have an admin interface. To do this, open the polls/admin.py
file, and edit it to look like this:polls/admin.py¶
from django.contrib import admin from .models import Question admin.site.register(Question)