There are various ways to install the Django framework. You can download Django from its main site 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
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. 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
||Allows install on virtual Python environment.Dependencies are taken care of automatically.||Latest version may not be available|
|Download from main site as
||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
||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
Once I finish these steps, I'll
also describe the steps to install Django from a
tar.gz file and from git -- using
which can be helpful if you want to try out the latest Django
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 3.2. Django 3.2 requires that you either have a Python 3.6 or higher release (3.7, 3.8 or 3.9).
If this is the first time you use Python, it's important to note Python 3 is considerably different than Python 2. This is important to note because Python 2 has remained stubbornly entrenched to the point Python 2.7.18 came out in April 2020, so it's certainly possible for a workstation/server in 2021 to still have Python 2 on it -- 2020 was slated to be the end of life year for Python 2 when no more releases are made, but this date had previously been set to 2015. So in this sense, make sure you use Python 3 -- as will be described shortly in listing 1-1.
As far as Django's core is concerned, the earlier Django 1.11 LTS version is compatible with both Python 2 and Python 3. However, if you want to work with the latest Django features that are part of Django 3.2 LTS, you inevitably need to use Python 3. Switch to the "Install Django 1.11 LTS" section if you plan to use Django 1.11.
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
/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 3 is
installed correctly and accessible from anywhere on your system.
Open a terminal and type
python3 or inclusively
python3.9 -- these variations depend on how you installed Python or if you have multiple Python versions on the same system. In either scenario, you should enter a
Python interactive session like the one illustrated in listing
Listing 1-1 - Python interactive session
[user@~]$ python3 Python 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information.
If you aren't able to enter a Python interactive session that explicitly indicates Python 3.6, Python 3.7, Python 3.8 or Python 3.9, 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. Most Python distributions include the
pip executable and just like the
python executable, will be named either
pip3.8, depending on the underlying Python version. 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@~]$ pip3 install --upgrade pip Collecting pip Using cached pip-21.0.1-py3-none-any.whl (1.5 MB) Installing collected packages: pip Successfully installed pip-21.0.1
As you can see in listing 1-2, to
update pip you invoke the
pip executable with the
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:
python3 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
executable with pip, as show in listing 1-3.
Listing 1-3. Install virtualenv with pip
[user@~]$ pip3 install virtualenv Collecting virtualenv Downloading virtualenv-20.0.17-py2.py3-none-any.whl (2.0MB) Installing collected packages: virtualenv Successfully installed virtualenv-20.0.17
As illustrated in listing 1-3,
pip3 automatically downloads and installs the requested
package. Similar to the
pip3 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
Listing 1-4. Create virtual Python environment with virtualenv
[user@~]$ virtualenv --python=python3 coffeehouse created virtual environment CPython3.8.5.final.0-64 in 686ms creator CPython3Posix(dest=/python/coffeehouse, clear=False, global=False) seeder FromAppData(download=False, distro=latest, retrying=latest, pkg_resources=latest, pyparsing=latest, pip=latest, urllib3=latest, contextlib2=latest, pytoml=latest, six=latest, requests=latest, pep517=latest, CacheControl=latest, lockfile=latest, webencodings=latest, distlib=latest, appdirs=latest, colorama=latest, ipaddr=latest, html5lib=latest, idna=latest, certifi=latest, msgpack=latest, wheel=latest, setuptools=latest, progress=latest, packaging=latest, chardet=latest, via=copy, app_data_dir=/home/django/.local/share/virtualenv/seed-app-data/v1.0.1.debian) activators BashActivator,CShellActivator,FishActivator,PowerShellActivator,PythonActivator,XonshActivator
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 3.5, Python 3.6, Python 3.7) 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
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
coffeehouse. 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 | +-chardetect | +-distro3 | +-easy_install | +-pip | +-python | +-wheel | +---+-<lib> | +---+-<pyvenv.cfg>
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, python3 & python3.8; in addition to activate, activate.csh & activate_this.py).
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
lib directory is a copy of the global Python
installation libraries and where packages for the virtual
environment are installed and the
pyvenv.json file contains metadata about the virtualenv, such as: the Python implementation backing the virtualenv; the Python version backing the virtualenv; and the virtualenv version, among other things.
The most important part of the
virtual environment is the executables under the
directory. If you use any of these executables, such as
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
Even though access to different
virtual Python environments and executables is a powerful feature,
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
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
directory, a process illustrated in listing 1-6.
Listing 1-6 - Activate virtual Python environment
[user@~]$ source ./bin/activate [(coffeehouse)user@~] $ # NOTE: source is a Unix/Linux specific command, for other OS just execute activate
Notice in listing 1-6 how after
activate executable, the command prompt
adds the virtual environment name between parenthesis. This means
the executables under the
bin directory of the virtual
coffeehouse 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. coffeehouse) 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
pipexecutables 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.
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==3.2 Collecting Django==3.2 Downloading Django-3.2-py3-none-any.whl (7.9 MB) |████████████████████████████████| 7.9 MB 1.7 MB/s Collecting pytz Downloading pytz-2021.1-py2.py3-none-any.whl (510 kB) |████████████████████████████████| 510 kB 21.0 MB/s Collecting asgiref<4,>=3.3.2 Downloading asgiref-3.3.4-py3-none-any.whl (22 kB) Collecting sqlparse>=0.2.2 Downloading sqlparse-0.4.1-py3-none-any.whl (42 kB) |████████████████████████████████| 42 kB 8.0 MB/s Installing collected packages: pytz, asgiref, sqlparse, Django Successfully installed Django-3.2 asgiref-3.3.4 pytz-2021.1 sqlparse-0.4.1
pip install task
in listing 1-7 uses the
Django==3.2 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 can take time 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-3.2.tar.gz Processing /home/Downloads/Django-3.2.tar.gz Collecting asgiref<4,>=3.3.2 Using cached asgiref-3.3.4-py3-none-any.whl (22 kB) Collecting pytz Using cached pytz-2021.1-py2.py3-none-any.whl (510 kB) Collecting sqlparse>=0.2.2 Using cached sqlparse-0.4.1-py3-none-any.whl (42 kB) Building wheels for collected packages: Django Building wheel for Django (setup.py) ... done Created wheel for Django: filename=Django-3.2-py3-none-any.whl size=7881998 sha256=c55867f71da839229e471f56494f007f954ecc4b12790768adb82b29fd1d6ea5 Stored in directory: /home/django/.cache/pip/wheels/a7/a1/f9/0515f4daae5205a87aa44e90b9ea0889225775aed0ec13bded Successfully built Django Installing collected packages: asgiref, pytz, sqlparse, Django Successfully installed Django-3.2 asgiref-3.3.4 pytz-2021.1 sqlparse-0.4.1
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-req-build-n53i0dt1 Running command git clone -q https://github.com/django/django.git /tmp/pip-req-build-n53i0dt1 Installing build dependencies ... done Getting requirements to build wheel ... done Preparing wheel metadata ... done Requirement already satisfied: sqlparse>=0.2.2 in /python/coffeehouse/lib/python3.8/site-packages (from Django==4.0.dev20210415151422) (0.4.1) Requirement already satisfied: pytz in /python/coffeehouse/lib/python3.8/site-packages (from Django==4.0.dev20210415151422) (2021.1) Requirement already satisfied: asgiref>=3.3.2 in /python/coffeehouse/lib/python3.8/site-packages (from Django==4.0.dev20210415151422) (3.3.4) Building wheels for collected packages: Django Building wheel for Django (PEP 517) ... done Created wheel for Django: filename=Django-4.0.dev20210415151422-py3-none-any.whl size=7880730 sha256=63543a0bf0f22734559accf7649103b3bf20d38ae244d04d18217e272ea20dc8 Stored in directory: /tmp/pip-ephem-wheel-cache-oa2p_5k9/wheels/ac/75/87/0d53012d5538585dfc1af6759f827ad226f8b49c5dfab1f8b2 Successfully built Django Installing collected packages: Django Attempting uninstall: Django Found existing installation: Django 3.2 Uninstalling Django-3.2: Successfully uninstalled Django-3.2 Successfully installed Django-4.0.dev20210415151422
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: Enumerating objects: 474458, done. remote: Counting objects: 100% (1905/1905), done. remote: Compressing objects: 100% (972/972), done. remote: Total 474458 (delta 1035), reused 1531 (delta 810), pack-reused 472553 Receiving objects: 100% (474458/474458), 201.25 MiB | 16.74 MiB/s, done. Resolving deltas: 100% (346548/346548), done. # Assuming Django Git download made to /home/Downloads/django/ [user@~]$ pip install /home/Downloads/django/ Processing /home/Downloads/django Installing build dependencies ... done Getting requirements to build wheel ... done Preparing wheel metadata ... done Requirement already satisfied: pytz in /python/coffeehouse/lib/python3.8/site-packages (from Django==4.0.dev20210415151422) (2021.1) Requirement already satisfied: asgiref>=3.3.2 in /python/coffeehouse/lib/python3.8/site-packages (from Django==4.0.dev20210415151422) (3.3.4) Requirement already satisfied: sqlparse>=0.2.2 in /python/coffeehouse/lib/python3.8/site-packages (from Django==4.0.dev20210415151422) (0.4.1) Building wheels for collected packages: Django Building wheel for Django (PEP 517) ... done Created wheel for Django: filename=Django-4.0.dev20210415151422-py3-none-any.whl size=7880730 sha256=106a743f5c4d6786a6dfe08f7a44b31d008c709943fbcf574ce3b5e5f43bb0c8 Stored in directory: /tmp/pip-ephem-wheel-cache-tc9clgf3/wheels/d9/36/05/2eb730584428ef792c83b13bccc8a94b97f272459125c8eca3 Successfully built Django Installing collected packages: Django Attempting uninstall: Django Found existing installation: Django 4.0.dev20210415151422 Uninstalling Django-4.0.dev20210415151422: Successfully uninstalled Django-4.0.dev20210415151422 Successfully installed Django-4.0.dev20210415151422
Notice in listing 1-9 the syntax
to download a remote Git repository is
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.