Install Django

There are various ways to install the Django framework. You can download Django from its main site ^[7]and install it like a regular Python application. You can also download and install Django via an operating system (OS) package administration tool such as apt-get -- available on Linux distributions.

Yet another option is to install Django is to download it via the Python package manager pip. And yet another alternative is to install Django directly from its source on github^[8]. The list of Django installation options including their pros and cons is presented in Table 1-1.

Table 1-1. Django installation options - Pros and Cons

Approach	Pros	Cons
Download/install with `pip` Python package manager(Recommended option)	Allows install on virtual Python environment.Dependencies are taken care of automatically.	Latest version may not be available
Download from main site as `tar.gz` file.	Easiest access to latest Django stable release.	Requires manual download and install.Requires additional management of Django dependencies (if not using pip)
Download from Git.	Access to the latest Django features.	Can contain bugs.Requires additional management of Django dependencies (if not using pip)
Download/install from OS package manager (`apt-get`)	Easy to install.Dependencies are taken care of automatically.	Latest version may not be available.Installed on global Python environment.

As emphasized in table 1-1, the recommended option to install Django is to use the Python pip package manager because it provides the most flexibility. Next, I'll describe each of the steps to install Django using this approach and more importantly how to get up and running with pip.

Once I finish these steps, I'll also describe the steps to install Django from a tar.gz file and from git -- using pip -- which can be helpful if you want to try out the latest Django features.

Install Python (Pre-requisite)

Since Django is built on Python, you first need to install Python to run Django. The latest Django long term release (LTS) which is the focus of this book is version 1.11. Django 1.11 requires that you either have a Python 2.7.x release or a Python 3.4 or higher release (3.5 or 3.6).

If this is the first time you use Python, it's important to note Python 2 and Python 3 are considerably different. But while it's certainly true Python 3 is the future, be aware the future has been in the making since 2008 -- when the first Python 3 release came to light -- and Python 2 has remained stubbornly entrenched to the point Python 2.7.13 came out in December 2016.

So should you use Python 2 or Python 3 with Django ? As far as Django's core is concerned, it's compatible with both, so you can easily switch between Python 2 and Python 3. Where it gets a little more tricky, is when it comes to third party Python packages and the Django Python code you plan to write yourself.

While many third party Python packages have been upgraded to run on Python 3, this process has been sluggish. As I already pointed out, Python 3 has been almost 10 years in the making, so be aware that if you take the Python 3 route, you may encounter third party Python packages that won't work with Python 3.

When it comes to your own Django application code, the ideal choice is to make your code both Python 2 & Python 3 compatible -- just like Django's core -- it isn't that hard and I'll use this technique throughout the book. The sidebar contains more details on this topic of writing Python 2 and Python 3 compatible code.

Now, if want to stick to Python 2, just be aware Django 1.11 will be the last Django release to support Python 2 -- scheduled to be supported until around April 2020 -- so if you eventually upgrade to something higher than Django 1.11, you'll also need to upgrade all your application code to Python 3 -- which is why I recommend the dual Python 2 & Python 3 compatibility technique. If you want to stick to Python 3, that's the future, just be aware that as described earlier, some third party packages might not work with Python 3.

Django compatibility with Python 2 & Python 3

Django uses Six^[9] to run Python 2 and Python 3 compatible logic. Six is a set of utilities that wraps over the differences between Python 2 and Python 3, allowing that same logic to operate equally in either Python 2 and Python 3. The Django framework's internals -- which you'll rarely if ever need to inspect or modify -- already use this technique.

However, if you plan to write your Django application code to be compatible with both Python 2 and Python 3 , then you'll need to be a little more aware of how you write it. Django publishes its own guidelines on the various syntax and techniques you need to follow to make Django application code work with both Python 2 and Python 3^[10], techniques that are also used throughout the book.

If you use a Unix/Linux OS, Python is very likely installed on your system. If you type which python on a Unix/Linux terminal and it returns a response (e.g. /usr/bin/python) it indicates the location of the Python executable, if there is no response it indicates the Python executable is not available on the system.

If you don't have Python on your system and you're using a Debian or Ubuntu Linux distribution, you can use the OS package manager apt-get to install Python by typing: apt-get install python. If you have a Unix/Linux distribution that is not Debian or Ubuntu and you need to install Python, consult your Unix/Linux documentation for available Python packages or download the Python sources from http://python.org/download/ to do the installation.

If you have a system that runs on a Windows OS or macOS, Python installers are available for download from http://python.org/download/.

Irrespective of your system's OS, once you've finished the Python installation, ensure Python is installed correctly and accessible from anywhere on your system. Open a terminal and type python, you should enter a Python interactive session like the one illustrated in listing 1-1.

Listing 1-1 - Python interactive session

[user@~]$ python
Python 2.7.12 (default, Nov 19 2016, 06:48:10) 
[GCC 5.4.0 20160609] on linux2
Type "help", "copyright", "credits" or "license" for more information.

If you aren't able to enter a Python interactive session, review the Python installation process because you will not be able to continue with the following sections.

Update or install pip package manager (Pre-requisite)

To make Python package installation and management easier, Python uses a package manager called pip. If you're using Python 2.7.9 (or greater 2.x branch) or Python 3.4 (or a greater 3.x branch), pip comes installed by default. Now let's upgrade pip on your system as shown in listing 1-2, if you don't have pip on your system, I'll provide instructions shortly on how to get it.

Listing 1-2. Update pip package manager

[user@~]$ pip install --upgrade pip
Collecting pip
  Downloading pip-9.0.1-py2.py3-none-any.whl (1.3MB)
Installing collected packages: pip
  Found existing installation: pip 8.1.1
Successfully installed pip-9.0.1

As you can see in listing 1-2, to update pip you invoke the pip executable with the arguments install --upgrade pip. Upon execution, pip searches for a package by the provided name -- in this case pip itself -- downloads it and performs an upgrade in case it's already installed. If the installation output on your system is similar to the one in listing 1-2 -- without any errors -- you have successfully updated pip.

If you see an error like The program 'pip' is currently not installed or pip not found, it means your Python installation is not equipped with pip. In this case, you'll need to install the pip executable by downloading https://bootstrap.pypa.io/get-pip.py and then executing the downloaded file with the command: python get-pip.py. Once the pip executable is installed, run the pip update procedure from listing 1-2.

With pip on your system, you're ready to move on to the next step.

Install virtualenv (Optional pre-requisite)

Virtualenv is not essential to develop Django applications, but I highly recommend you use it because it allows you to create virtual Python environments on a single system. By using virtual Python environments, applications can run in their own 'sandbox' in isolation of other Python applications. Initially virtualenv can appear to be of little benefit, but it can be of tremendous help for tasks like replicating a development environment to a production environment and avoiding version conflicts that can arise between different applications.

Without virtualenv you can still proceed to install Django and any other Python package using pip, but the issue is all packages are installed under the global Python installation. Initially this can seem convenient, because you only need to install packages once in the global Python installation. But it's not that convenient if you think about some of the following questions.

What happens if a new Django version is released after your first project and you want to start a second project ? Do you upgrade the first project to run on the new Django version or start the second project as if the new Django version doesn't exist ? The first option requires additional work, while the second option requires you to develop on an outdated Django version. By using virtual Python environments you avoid this problem, because each project can run its own Django version in isolation.

If you consider this potential version conflict for any Python package, you'll realize why I recommend you use virtualenv. Many Python packages have specific version dependencies (e.g. Package A depends on package B version 2.3 and package C version 1.5). If you update a new package with specific cross-dependency versions, it can be very easy to break a Python installation if you're using a global Python installation. With virtualenv you can have multiple Python installations without them interfering with one another.

Now that I've explained the benefits of virtualenv, lets install the virtualenv executable with pip, as show in listing 1-3.

Listing 1-3. Install virtualenv with pip

[user@~]$  pip install virtualenv
Downloading/unpacking virtualenv
  Downloading virtualenv-15.1.0.tar.gz (1.8Mb): 1.8Mb downloaded
  Running setup.py egg_info for package virtualenv   
  Installing collected packages: virtualenv
  Running setup.py install for virtualenv
  Installing virtualenv script to /usr/local/bin
  Installing virtualenv-2.7 script to /usr/local/bin
Successfully installed virtualenv
Cleaning up...

As illustrated in listing 1-3, pip automatically downloads and installs the requested package. Similar to the pip executable, a virtualenv executable is also installed that should be accessible from anywhere on your system. The virtualenv executable allows you to create virtual Python environments. Listing 1-4 illustrates how to create a virtual Python environment with virtualenv.

Listing 1-4. Create virtual Python environment with virtualenv

[user@~]$ virtualenv --python=python3 mydjangosandbox
Already using interpreter /usr/bin/python3
Using base prefix '/usr'
New python executable in /mydjangosandbox/bin/python3
Also creating executable in /mydjangosandbox/bin/python
Installing setuptools, pkg_resources, pip, wheel...done.

The virtualenv executable accepts several parameters. The task in listing 1-4 makes use of the --python flag , which tells virtualenv to create a virtual Python based on the python3 executable, creating a Python 3 virtual environment. This is a common option when you have multiple Python versions on an OS (e.g. Python 2 and Python 3) and you need to specify the Python version with which to create the virtualenv. You can omit the --python flag, just be aware that doing so the virtualenv is created with the default OS python executable.

By default, virtualenv creates a pristine virtual Python environment like the one you had when you made the initial Python global installation. Following virtualenv parameters, you only need to specify an argument for the name of the virtual Python environment, which in the case of listing 1-4 is mydjangosandbox. Upon execution, virtualenv creates a directory with the virtual Python environment whose contents are illustrated in listing 1-5.

Listing 1-5 - Virtual Python environment directory structure

+<virtual_environment_name>
|
|
+---+-<bin>
|   |
|   +-activate
|   +-easy_install
|   +-pip
|   +-python
    +-python-config
|   +-wheel
|
+---+-<include>
|
+---+-<lib>
|
+---+-<local>^†
|
+---+-<share>

Tip Depending on the Python version used to create the virtualenv, the bin directory can contain multiple aliases or versions of the same command (e.g. In addition to python, python2.7 & python3; in addition to activate, activate.csh & activate_this.py).

Note^† local folder is only included in a Python 2 virtualenv and links to top level directories of the virtual directory to simulate a Python installation.

As illustrated in listing 1-5, a virtual Python environment has a similar directory structure to a global Python installation. The bin directory contains executables for the virtual environment, the include directory is linked to the global Python installation header files, the lib directory is a copy of the global Python installation libraries and where packages for the virtual environment are installed and the share directory is used to place shared Python packages.

The most important part of the virtual environment is the executables under the bin directory. If you use any of these executables, such as pip, easy_install, python or wheel they execute under the context of the virtual Python environment. For example, the pip under the bin folder installs packages for the virtual environment. Similarly, an application that runs on the python executable under the bin folder is only able to load packages installed on the virtual Python environment. This is the 'sandbox' behavior I mentioned previously.

Even though access to different virtual Python environments and executables is a powerful feature, having different pip and python executables for multiple virtual Python environments and the executables of the global Python installation itself, can become confusing due to long access paths and relative paths.

For this reason, virtualenv has a mechanism to load virtual environments so that if you execute pip, python or any other executable from anywhere on your system, the executables from a selected virtual environment are used (instead of the default global Python installation executables). This is achieved with the activate executable inside the bin directory, a process illustrated in listing 1-6.

Listing 1-6 - Activate virtual Python environment

[user@~]$ source ./bin/activate
[(mydjangosandbox)user@~] $ 
# NOTE: source is a Unix/Linux specific command, for other OS just execute activate

Notice in listing 1-6 how after invoking the activate executable, the command prompt adds the virtual environment name between parenthesis. This means the executables under the bin directory of the virtual Python environment mydjangosandbox are used over those in the global Python installation. To exit a virtual Python environment just type deactivate and you fallback to using the global Python installation executables.

As you've now learned, virtualenv works transparently allowing you to maintain different Python installations each with its own set of executables like the main python interpreter and the pip package manager. You only need to take care of switching between virtual environments so you install and run Python applications in the appropriate virtual environment.

Note In future sections I won't make any reference to virtualenv (e.g. mydjangosandbox) since it isn't directly related to Django. Though I recommend you use virtualenv, I'll leave it up to you if you want to keep using the global Python installation python and pip executables for everything or if you prefer to keep virtual Python environments with their own executables to make Python application management easier. So when you see Python executables referenced in the book, assume they are global or from a virtualenv, whichever you're using.

Install Django

Once you have all the previous tools working on your system, the actual Django installation is very simple. Listing 1-7 illustrates how to install Django using pip.

Listing 1-7. Install Django with pip

[user@~]$ pip install Django==1.11
Downloading/unpacking Django==1.11
Collecting Django==1.11
  Downloading Django-1.11-py2.py3-none-any.whl (6.9MB)
    100% |████████████████████████████████| 6.9MB 95kB/s 
Collecting pytz (from Django==1.11)
  Downloading pytz-2017.2-py2.py3-none-any.whl (484kB)
    100% |████████████████████████████████| 491kB 735kB/s 
Installing collected packages: pytz, Django
Successfully installed Django-1.11 pytz-2017.2

The pip install task in listing 1-7 uses the Django==1.11 syntax to tell pip to download and install the Django 1.11 version. With this same syntax you can install any specific Django version. If you don't specify a package version, pip downloads and installs the most recent available version for the specified package.

Sometimes a Django release may take a few days to become available through pip, in which case you'll receive an error. In such cases you can download the release directly from the Django main site at https://www.djangoproject.com/download/. Once you download the release file in tar.gz format, you can use pip to make the installation as illustrated in listing 1-8.

Listing 1-8. Install Django from local tar.gz file with pip

[user@~]$ pip install /home/Downloads/Django-1.11.tar.gz 
Processing /home/Downloads/Django-1.11.tar.gz
Collecting pytz (from Django==1.11)
  Using cached pytz-2017.2-py2.py3-none-any.whl
Building wheels for collected packages: Django
  Running setup.py bdist_wheel for Django ... done
  Stored in directory: /home/ubuntu/.cache/pip/wheels/56/bf/24/
                              f44162e115f4fe0cfeb4b0ae99b570fb55a741a8d090c9894d
Successfully built Django
Installing collected packages: pytz, Django
Successfully installed Django-1.11 pytz-2017.2

Notice in listing 1-8 how pip is capable of installing Python packages directly from a compressed file on the local file system.

Install Django from Git

If you want to use the most recent functionalities available in Django, then you'll need to install Django from its Git repository. The Git repository contains the latest changes made to Django. Even though the Django Git version can be unstable, it's the only way to develop with the newest Django features or get bug-fixes for problems that aren't yet available in public releases.

Note You need to install Git to execute the following tasks. You can download Git for several OSes at http://git-scm.com/

Just like the prior pip installation examples, pip is sufficiently flexible to make a Django installation from Git. There are two alternatives to use pip with Git. You can provide the remote Django Git repository, in which case pip clones the repository locally and discards it after the installation, as illustrated listing 1-9. Or you can clone the Django Git repository locally -- where you'll be able to make modifications at a later time -- and then run pip to do the installation, as illustrated in listing 1-10.

Listing 1-9. Install Django from remote Git with pip

[user@~]$ pip install git+https://github.com/django/django.git
Collecting git+https://github.com/django/django.git
  Cloning https://github.com/django/django.git to ./pip-31j_bcqa-build
Requirement already satisfied: pytz in /python/mydjangosandbox/lib/python3.5/site-packages
                                                        (from Django==2.0.dev20170408112615)
Installing collected packages: Django
      Successfully uninstalled Django-1.11
  Running setup.py install for Django ... done
Successfully installed Django-2.0.dev20170408112615

Listing 1-10. Download Django from Git and install locally with pip

[user@~]$ git clone https://github.com/django/django.git 
Cloning into django...
remote: Counting objects: 388550, done.
remote: Compressing objects: 100% (19/19), done.
remote: Total 388550 (delta 5), reused 0 (delta 0), pack-reused 388531
Receiving objects: 100% (388550/388550), 158.63 MiB | 968.00 KiB/s, done.
Resolving deltas: 100% (281856/281856), done.
Checking connectivity... done.

# Assuming Django Git download made to /home/Downloads/django/
[user@~]$ pip install /home/Downloads/django/
Processing /home/Downloads/django
Collecting pytz (from Django==2.0.dev20170408112615)
  Using cached pytz-2017.2-py2.py3-none-any.whl
Installing collected packages: pytz, Django
  Running setup.py install for Django ... done
Successfully installed Django-2.0.dev20170408112615 pytz-2017.2

Notice in listing 1-9 the syntax to download a remote Git repository is git+ followed by the remote Git location. In this case https://github.com/django/django.git represents the Django Git repository. In listing 1-10 the Django Git repository is cloned locally first and then pip is executed with the argument of the local Git repository directory.