Note: This guide assumes that you have Python installed on your machine - if you don’t, head to python.org/download/ and download and install Python for your Operating System
Step One: Install Django
1. Install Pip
Pip is currently the most popular package manager for Python and helps you to
manage the packages you require for you app (particularly useful is the
command - see Note 1).
You can install Pip with the instructions found at:
2. Install Virtualenv
Virtualenv sets up a Virtual Environment by creating a directory that contains packages that will only be accessible from the Virtual Environment. This means that other projects that you are working on won’t be affected if you install a conflicting package. Everything installed within the Virtual Environment is only accessed if it is currently activated.
To install Virtualenv, run the following:
3. Set up Virtual Environment
You can set up a Virtual Environment by simply running
name>, then activate it by sourcing the
bin/activate file in the Virtual
Create Virtual Environment
Activate Virtual Environment
Deactivate Virtual Environment
After running either of the first two commands you should see the name of the
Virtual Environment in brackets in your command line:
4. Install Django:
Ensuring that the virtualenv is activated, install Django with pip.
5. Start a Django Project
startproject to create a blank Django project in the current directory.
You should then see a basic welcome page for Django at http://localhost:8000/
Step Two: Setup a URL and View
1. Write the URLs
Open the urls.py file inside the django_quickstart directory and add the following url:
URL Pattern Breakdown:
url()contains your url pattern
r"^$"regular expression to match urls to
"django_quickstart.views.home"view to display for matched pattern
name="home"name given to pattern to allow it to be called inside code, such as links
The pattern here defines a regex with nothing between the line start
^ and end
$ of the url and maps requests to this url to the ‘home’ view inside of the
views.py file in the ‘django_quickstart’ directory.
The name=”home” simply allows the view to be referenced in other code as home (this can be namespaced to avoid clashing with another urls.py file defining the same name, eg ‘users:home’). An example of this would be in reversing urls to use in links:
3. Create a View
In the case of the example url pattern with a view declaration of
"django_quickstart.views.home", the views.py file would be found/created in
the ‘django_quickstart’ directory and the view would be called ‘home’ as in the
Class Based Views
It is important to note that class based views (where views are declared as classes instead of functions) are declared in a different way to function based views. Class based views are declared in url patterns as follows:
Please note that the view declaration does not have quotes around it as it calling the ‘as_view’ method from the class.
Please also note that in this example I have first imported the class based view called ‘Home’ from the views.py file in the ‘django_quickstart’ app.
The class based equivalent of the home view would then look like this:
Step Three: Create an App
Finally we can create an app to hold a specific group of objects, where we can define the Models to hold the data and the methods for dealing with it.
1. Create the app
Django projects are structured into multiple ‘apps’ that define a specific part of the overall project, for instance a ‘books’ app in the case of a project that helps to reference a library’s collection of books, and separate apps for ‘cds’, ‘dvds’, and ‘members’.
Apps can be created by either manually creating a directory with the following files:
..or by running:
..which will automatically generate the required files.
The app name must then be included in the INSTALLED_APPS list in the settings file (by default settings.py in the django_quickstart directory - see Note 2):
2. Create a model
Models can be thought of as being the nouns in your app, so in our case of an ‘animals’ app, you could add a model for a ‘Tiger’ and give it some properties, such as a name, and methods (essentially verbs) to give it something to do.
Django provides you with a number of fields that you can define the properties of a model with, such as CharField (limited text field), TextField (unlimited text field), EmailField, ImageField, and SlugField, which determine how the database schema should be set up and how the field should be displayed and validated in a form, https://docs.djangoproject.com/en/dev/ref/models/fields/.
Mixins for Multiple Inheritance
Often you want to reuse certain traits that are shared among different objects, in this case you can implement this very simply with abstract classes:
3. Add the Model to the Database Schema
python manage.py syncdb to setup the database, this
handles automatically creating tables in the database from the models.
A third party app called http://south.readthedocs.io/en/latest/ can
then be used to make additional changes.
You can play around with the model to try methods for creating a new instance and retreiving existing ones:
python manage.py shell then try the following:
Create an instance
Press ctrl-d to exit the shell.
4. And the Rest
By now we have a simple Django Project with an ‘animals’ app containing a Tiger model. With this basic setup it should be possible to discover how to create a more interesting view for displaying the tigers, (e.g. as a list of their names).
Note 1: Pip Freeze Command
The ‘pip freeze’ command can be used to get the currently installed packages and their versions. This can be redirected into a file from which you can later install them, for instance when setting up on another machine, as follows:
Redirect the output of pip freeze (with the required packages) into a text file:
Install the required packages from the text file:
Note 2: Settings File
You can specify different files for Django’s settings, which is especially useful when you need to set up seperate environments, such as live, staging and dev.
Different settings files can be used using the –settings flag, for example:
Note 3: Database Migrations
Normally updating the database schema like this (by running syncdb again) is not a good idea, as any existing data will have to be reformatted to fit the new schema and any expected data (for instance a new field that is NOT NULL) would have to be made up for existing rows.
This is where database migrations are useful - allowing you to make changes to the database schema without worrying about many of the issues with schema changes. The references to these changes (in a directory called migrations) are also then uploaded to production or staging environments, allowing you to make the schema changes to these environments too with a simple command.
Prior to Django version 1.7 this was only available with a Third Party tool called South, however migrations have now been added to Django core:
..apparently thanks to some very generous backers on Kickstarter:
Some info on how South migrations work: