Quick intro:
This is a quick Django tutorial where we'll build a recipe sharing web app. The final application will allow users to create profiles, recipe lists and share them with other users. Django is one of the best web frameworks for rapid prototyping.

This tutorial assumes some basic knowledge of the Python programming language. Check out this site if you need some Python tutorials. Or you can continue below and pick up the language along the way.

Django 1.10 +
Python 3.5
Mac or Windows machine
Code editor (I'm using Atom)
Basic Unix commands

Shall we start?

Initial setup:

Skip this section if you've already installed Django, a virtual environment and have set up a workspace in your editor of choice.

Let’s begin by setting up a virtual environment - A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. Read more

Open Terminal and run this command:
pip install virtualenv

Next, we run this command:
pip install virtualenvwrapper

We'll now add the following two lines to our ~/.bash_profile:

export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh

If you're new to everything we've just done, I highly encourage you to read this guide.

With the virtualenvwrapper successfully installed, we can create  a virtual environment with this command:
mkvirtualenv foodiegramapp

You can call your virtual environment whatever you like.

Let me explain what we've just done. The app itself is still called Foodiegram. foodiegramapp is simply the name of our virtual environment. This is where our application will live. We will also install the necessary packages in this environment, including the version of Django we want to use for this particular project.

You should be inside the newly created virtual environment. Your Terminal should show the name of the environment in parentheses, like this (foodiegramapp). You might also see the name of your machine. This means that you're currently working in the foodiegramapp virtual environment. You can exit the environment with this command: deactivate. To return to our virtual environment, run this command: workon foodiegramapp. You can create as many virtual environments as you want and use the workon command to switch between them.

Our virtual environment should be up and running. Now we can install Django in this virtual environment using this command:
pip install Django==1.10

Wait for the installation to complete and we should have Django version 1.10 installed. Run pip freeze on the Terminal, you should see all the Python packages installed in this virtual environment.

That's it! We can start building our project. Run this command in the Terminal:
django-admin startproject foodiegram

The previous command creates a directory called foodiegram. Run the ls command to see the content of this directory - you should have something like this:


This may look a bit confusing. We have a foodiegram directory within a foodiegram directory. We can fix this. By convention, we should rename the outer foodiegram folder to root or src. Let's rename the outer directory to root. First, let's go one directory above with this command: cd .. then run this command: mv foodiegram root

The outer foodiegram directory should now be root - as in project root.

Our file structure should look like this:

Here's a brief overview of the files from above:

  • The root directory is our project container.
  • manage.py is a command-line utility that allows you to interact with your project.
  • The foodiegram directory is the Python package for our project
  • __init__.py is an empty file that tells Python that this directory should be considered a Python package.
  • settings.py this is our configuration file where we configure our Django installation.
  • urls.py this is our URL declaration file for this project.
  • wsgi.py is a specification that describes how a web server communicates with web applications.

This is all you need to know about these files for now. We will explore them in more detail as we progress.

Let's go back to the Terminal and make sure we're in the root directory and run this command:
python manage.py migrate

This command basically runs the database migrations. Django is importing the necessary models into our database. By default, Django uses SQLite. The command should generate a db.sqlite3 file in the root directory. We're going to stick with SQLite for this project but just to let you know it is possible to use other databases like PostgreSQL or MongoDB if we wanted.

Now, let's run this command:
./manage.py runserver

Open a web browser and go to

You will see the Django default Homepage.

You can stop the server by clicking Control and C

Well done! You've completed part 1. Go ahead, give yourself a pat on the back. You deserve it. Stick around for Part  2.