| 1 |
===================== |
| 2 |
How to install Django |
| 3 |
===================== |
| 4 |
|
| 5 |
This document will get you up and running with Django. |
| 6 |
|
| 7 |
Install Python |
| 8 |
============== |
| 9 |
|
| 10 |
Django is a Python web framework. See :ref:`faq-python-version-support` for |
| 11 |
details. |
| 12 |
|
| 13 |
Get the latest version of Python at https://www.python.org/downloads/ or with |
| 14 |
your operating system's package manager. |
| 15 |
|
| 16 |
.. admonition:: Python on Windows |
| 17 |
|
| 18 |
If you are just starting with Django and using Windows, you may find |
| 19 |
:doc:`/howto/windows` useful. |
| 20 |
|
| 21 |
Install Apache and ``mod_wsgi`` |
| 22 |
=============================== |
| 23 |
|
| 24 |
If you just want to experiment with Django, skip ahead to the next |
| 25 |
section; Django includes a lightweight web server you can use for |
| 26 |
testing, so you won't need to set up Apache until you're ready to |
| 27 |
deploy Django in production. |
| 28 |
|
| 29 |
If you want to use Django on a production site, use `Apache`_ with |
| 30 |
`mod_wsgi`_. mod_wsgi operates in one of two modes: embedded |
| 31 |
mode or daemon mode. In embedded mode, mod_wsgi is similar to |
| 32 |
mod_perl -- it embeds Python within Apache and loads Python code into |
| 33 |
memory when the server starts. Code stays in memory throughout the |
| 34 |
life of an Apache process, which leads to significant performance |
| 35 |
gains over other server arrangements. In daemon mode, mod_wsgi spawns |
| 36 |
an independent daemon process that handles requests. The daemon |
| 37 |
process can run as a different user than the web server, possibly |
| 38 |
leading to improved security. The daemon process can be restarted |
| 39 |
without restarting the entire Apache web server, possibly making |
| 40 |
refreshing your codebase more seamless. Consult the mod_wsgi |
| 41 |
documentation to determine which mode is right for your setup. Make |
| 42 |
sure you have Apache installed with the mod_wsgi module activated. |
| 43 |
Django will work with any version of Apache that supports mod_wsgi. |
| 44 |
|
| 45 |
See :doc:`How to use Django with mod_wsgi </howto/deployment/wsgi/modwsgi>` |
| 46 |
for information on how to configure mod_wsgi once you have it |
| 47 |
installed. |
| 48 |
|
| 49 |
If you can't use mod_wsgi for some reason, fear not: Django supports many other |
| 50 |
deployment options. One is :doc:`uWSGI </howto/deployment/wsgi/uwsgi>`; it works |
| 51 |
very well with `nginx`_. Additionally, Django follows the WSGI spec |
| 52 |
(:pep:`3333`), which allows it to run on a variety of server platforms. |
| 53 |
|
| 54 |
.. _Apache: https://httpd.apache.org/ |
| 55 |
.. _nginx: https://nginx.org/ |
| 56 |
.. _mod_wsgi: https://modwsgi.readthedocs.io/en/develop/ |
| 57 |
|
| 58 |
.. _database-installation: |
| 59 |
|
| 60 |
Get your database running |
| 61 |
========================= |
| 62 |
|
| 63 |
If you plan to use Django's database API functionality, you'll need to make |
| 64 |
sure a database server is running. Django supports many different database |
| 65 |
servers and is officially supported with PostgreSQL_, MariaDB_, MySQL_, Oracle_ |
| 66 |
and SQLite_. |
| 67 |
|
| 68 |
If you are developing a small project or something you don't plan to deploy in |
| 69 |
a production environment, SQLite is generally the best option as it doesn't |
| 70 |
require running a separate server. However, SQLite has many differences from |
| 71 |
other databases, so if you are working on something substantial, it's |
| 72 |
recommended to develop with the same database that you plan on using in |
| 73 |
production. |
| 74 |
|
| 75 |
In addition to the officially supported databases, there are :ref:`backends |
| 76 |
provided by 3rd parties <third-party-notes>` that allow you to use other |
| 77 |
databases with Django. |
| 78 |
|
| 79 |
To use another database other than SQLite, you'll need to make sure that the |
| 80 |
appropriate Python database bindings are installed: |
| 81 |
|
| 82 |
* If you're using PostgreSQL, you'll need the `psycopg`_ or `psycopg2`_ |
| 83 |
package. Refer to the :ref:`PostgreSQL notes <postgresql-notes>` for further |
| 84 |
details. |
| 85 |
|
| 86 |
* If you're using MySQL or MariaDB, you'll need a :ref:`DB API driver |
| 87 |
<mysql-db-api-drivers>` like ``mysqlclient``. See :ref:`notes for the MySQL |
| 88 |
backend <mysql-notes>` for details. |
| 89 |
|
| 90 |
* If you're using SQLite you might want to read the :ref:`SQLite backend notes |
| 91 |
<sqlite-notes>`. |
| 92 |
|
| 93 |
* If you're using Oracle, you'll need to install oracledb_, but please read the |
| 94 |
:ref:`notes for the Oracle backend <oracle-notes>` for details regarding |
| 95 |
supported versions of both Oracle and ``oracledb``. |
| 96 |
|
| 97 |
* If you're using an unofficial 3rd party backend, please consult the |
| 98 |
documentation provided for any additional requirements. |
| 99 |
|
| 100 |
And ensure that the following keys in the ``'default'`` item of the |
| 101 |
:setting:`DATABASES` dictionary match your database connection settings: |
| 102 |
|
| 103 |
* :setting:`ENGINE <DATABASE-ENGINE>` -- Either |
| 104 |
``'django.db.backends.sqlite3'``, |
| 105 |
``'django.db.backends.postgresql'``, |
| 106 |
``'django.db.backends.mysql'``, or |
| 107 |
``'django.db.backends.oracle'``. Other backends are :ref:`also available |
| 108 |
<third-party-notes>`. |
| 109 |
|
| 110 |
* :setting:`NAME` -- The name of your database. If you’re using SQLite, the |
| 111 |
database will be a file on your computer. In that case, ``NAME`` should be |
| 112 |
the full absolute path, including the filename of that file. You don’t need |
| 113 |
to create anything beforehand; the database file will be created |
| 114 |
automatically when needed. The default value, ``BASE_DIR / 'db.sqlite3'``, |
| 115 |
will store the file in your project directory. |
| 116 |
|
| 117 |
.. admonition:: For databases other than SQLite |
| 118 |
|
| 119 |
If you are not using SQLite as your database, additional settings such as |
| 120 |
:setting:`USER`, :setting:`PASSWORD`, and :setting:`HOST` must be added. |
| 121 |
For more details, see the reference documentation for :setting:`DATABASES`. |
| 122 |
|
| 123 |
Also, make sure that you've created the database by this point. Do that |
| 124 |
with "``CREATE DATABASE database_name;``" within your database's |
| 125 |
interactive prompt. |
| 126 |
|
| 127 |
If you plan to use Django's ``manage.py migrate`` command to automatically |
| 128 |
create database tables for your models (after first installing Django and |
| 129 |
creating a project), you'll need to ensure that Django has permission to create |
| 130 |
and alter tables in the database you're using; if you plan to manually create |
| 131 |
the tables, you can grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and |
| 132 |
``DELETE`` permissions. After creating a database user with these permissions, |
| 133 |
you'll specify the details in your project's settings file, see |
| 134 |
:setting:`DATABASES` for details. |
| 135 |
|
| 136 |
If you're using Django's :doc:`testing framework</topics/testing/index>` to test |
| 137 |
database queries, Django will need permission to create a test database. |
| 138 |
|
| 139 |
.. _PostgreSQL: https://www.postgresql.org/ |
| 140 |
.. _MariaDB: https://mariadb.org/ |
| 141 |
.. _MySQL: https://www.mysql.com/ |
| 142 |
.. _psycopg: https://www.psycopg.org/psycopg3/ |
| 143 |
.. _psycopg2: https://www.psycopg.org/ |
| 144 |
.. _SQLite: https://www.sqlite.org/ |
| 145 |
.. _oracledb: https://oracle.github.io/python-oracledb/ |
| 146 |
.. _Oracle: https://www.oracle.com/ |
| 147 |
|
| 148 |
.. _install-django-code: |
| 149 |
|
| 150 |
Install the Django code |
| 151 |
======================= |
| 152 |
|
| 153 |
Installation instructions are slightly different depending on whether you're |
| 154 |
installing a distribution-specific package, downloading the latest official |
| 155 |
release, or fetching the latest development version. |
| 156 |
|
| 157 |
.. _installing-official-release: |
| 158 |
|
| 159 |
Installing an official release with ``pip`` |
| 160 |
------------------------------------------- |
| 161 |
|
| 162 |
This is the recommended way to install Django. |
| 163 |
|
| 164 |
#. Install pip_. The easiest is to use the `standalone pip installer`_. If your |
| 165 |
distribution already has ``pip`` installed, you might need to update it if |
| 166 |
it's outdated. If it's outdated, you'll know because installation won't |
| 167 |
work. |
| 168 |
|
| 169 |
#. Take a look at :doc:`venv <python:tutorial/venv>`. This tool provides |
| 170 |
isolated Python environments, which are more practical than installing |
| 171 |
packages systemwide. It also allows installing packages without |
| 172 |
administrator privileges. The :doc:`contributing tutorial |
| 173 |
</intro/contributing>` walks through how to create a virtual environment. |
| 174 |
|
| 175 |
#. After you've created and activated a virtual environment, enter the command: |
| 176 |
|
| 177 |
.. console:: |
| 178 |
|
| 179 |
$ python -m pip install Django |
| 180 |
|
| 181 |
.. _pip: https://pip.pypa.io/ |
| 182 |
.. _standalone pip installer: https://pip.pypa.io/en/latest/installation/ |
| 183 |
|
| 184 |
.. _installing-distribution-package: |
| 185 |
|
| 186 |
Installing a distribution-specific package |
| 187 |
------------------------------------------ |
| 188 |
|
| 189 |
Check the :doc:`distribution specific notes </misc/distributions>` to see if |
| 190 |
your platform/distribution provides official Django packages/installers. |
| 191 |
Distribution-provided packages will typically allow for automatic installation |
| 192 |
of dependencies and supported upgrade paths; however, these packages will rarely |
| 193 |
contain the latest release of Django. |
| 194 |
|
| 195 |
.. _installing-development-version: |
| 196 |
|
| 197 |
Installing the development version |
| 198 |
---------------------------------- |
| 199 |
|
| 200 |
.. admonition:: Tracking Django development |
| 201 |
|
| 202 |
If you decide to use the latest development version of Django, |
| 203 |
you'll want to pay close attention to `the development timeline`_, |
| 204 |
and you'll want to keep an eye on the :ref:`release notes for the |
| 205 |
upcoming release <development_release_notes>`. This will help you stay |
| 206 |
on top of any new features you might want to use, as well as any changes |
| 207 |
you'll need to make to your code when updating your copy of Django. |
| 208 |
(For stable releases, any necessary changes are documented in the |
| 209 |
release notes.) |
| 210 |
|
| 211 |
.. _the development timeline: https://code.djangoproject.com/timeline |
| 212 |
|
| 213 |
If you'd like to be able to update your Django code occasionally with the |
| 214 |
latest bug fixes and improvements, follow these instructions: |
| 215 |
|
| 216 |
#. Make sure that you have Git_ installed and that you can run its commands |
| 217 |
from a shell. (Enter ``git help`` at a shell prompt to test this.) |
| 218 |
|
| 219 |
#. Check out Django's main development branch like so: |
| 220 |
|
| 221 |
.. console:: |
| 222 |
|
| 223 |
$ git clone https://github.com/django/django.git |
| 224 |
|
| 225 |
This will create a directory ``django`` in your current directory. |
| 226 |
|
| 227 |
#. Make sure that the Python interpreter can load Django's code. The most |
| 228 |
convenient way to do this is to use a virtual environment and pip_. The |
| 229 |
:doc:`contributing tutorial </intro/contributing>` walks through how to |
| 230 |
create a virtual environment. |
| 231 |
|
| 232 |
#. After setting up and activating the virtual environment, run the following |
| 233 |
command: |
| 234 |
|
| 235 |
.. console:: |
| 236 |
|
| 237 |
$ python -m pip install -e django/ |
| 238 |
|
| 239 |
This will make Django's code importable, and will also make the |
| 240 |
``django-admin`` utility command available. In other words, you're all |
| 241 |
set! |
| 242 |
|
| 243 |
When you want to update your copy of the Django source code, run the command |
| 244 |
``git pull`` from within the ``django`` directory. When you do this, Git will |
| 245 |
download any changes. |
| 246 |
|
| 247 |
.. _Git: https://git-scm.com/ |