2005-07-16 05:21:18 +08:00
|
|
|
=====================
|
|
|
|
How to install Django
|
|
|
|
=====================
|
|
|
|
|
2005-07-16 05:51:05 +08:00
|
|
|
This document will get you up and running with Django.
|
|
|
|
|
2005-11-12 11:24:32 +08:00
|
|
|
Install Python
|
|
|
|
==============
|
|
|
|
|
2018-03-05 14:12:18 +08:00
|
|
|
Django is a Python Web framework. See :ref:`faq-python-version-support` for
|
|
|
|
details.
|
2005-11-12 11:24:32 +08:00
|
|
|
|
2017-05-20 23:51:21 +08:00
|
|
|
Get the latest version of Python at https://www.python.org/downloads/ or with
|
2013-12-31 01:15:49 +08:00
|
|
|
your operating system's package manager.
|
2005-11-12 11:24:32 +08:00
|
|
|
|
2008-08-26 23:52:21 +08:00
|
|
|
.. admonition:: Django on Jython
|
|
|
|
|
2017-12-21 23:31:59 +08:00
|
|
|
Jython_ (a Python implementation for the Java platform) is not compatible
|
|
|
|
with Python 3, so Django ≥ 2.0 cannot run on Jython.
|
2008-08-26 23:52:21 +08:00
|
|
|
|
2017-12-21 23:31:59 +08:00
|
|
|
.. _jython: http://www.jython.org/
|
2008-08-26 23:52:21 +08:00
|
|
|
|
2012-03-02 12:27:46 +08:00
|
|
|
.. admonition:: Python on Windows
|
|
|
|
|
2014-03-20 02:38:12 +08:00
|
|
|
If you are just starting with Django and using Windows, you may find
|
|
|
|
:doc:`/howto/windows` useful.
|
2012-03-02 12:27:46 +08:00
|
|
|
|
2016-01-25 05:26:11 +08:00
|
|
|
Install Apache and ``mod_wsgi``
|
|
|
|
===============================
|
2005-07-16 05:51:05 +08:00
|
|
|
|
2010-08-28 10:40:57 +08:00
|
|
|
If you just want to experiment with Django, skip ahead to the next
|
2011-06-17 00:34:12 +08:00
|
|
|
section; Django includes a lightweight web server you can use for
|
2010-08-28 10:40:57 +08:00
|
|
|
testing, so you won't need to set up Apache until you're ready to
|
|
|
|
deploy Django in production.
|
|
|
|
|
2011-06-17 00:34:12 +08:00
|
|
|
If you want to use Django on a production site, use `Apache`_ with
|
2018-03-05 14:12:18 +08:00
|
|
|
`mod_wsgi`_. mod_wsgi operates in one of two modes: embedded
|
|
|
|
mode or daemon mode. In embedded mode, mod_wsgi is similar to
|
2010-08-28 10:40:57 +08:00
|
|
|
mod_perl -- it embeds Python within Apache and loads Python code into
|
|
|
|
memory when the server starts. Code stays in memory throughout the
|
|
|
|
life of an Apache process, which leads to significant performance
|
|
|
|
gains over other server arrangements. In daemon mode, mod_wsgi spawns
|
|
|
|
an independent daemon process that handles requests. The daemon
|
2010-10-09 16:12:50 +08:00
|
|
|
process can run as a different user than the Web server, possibly
|
2018-03-05 14:12:18 +08:00
|
|
|
leading to improved security. The daemon process can be restarted
|
2010-10-09 16:12:50 +08:00
|
|
|
without restarting the entire Apache Web server, possibly making
|
2010-08-28 10:40:57 +08:00
|
|
|
refreshing your codebase more seamless. Consult the mod_wsgi
|
|
|
|
documentation to determine which mode is right for your setup. Make
|
2018-03-05 14:12:18 +08:00
|
|
|
sure you have Apache installed with the mod_wsgi module activated.
|
2010-08-28 10:40:57 +08:00
|
|
|
Django will work with any version of Apache that supports mod_wsgi.
|
|
|
|
|
2011-10-22 12:30:10 +08:00
|
|
|
See :doc:`How to use Django with mod_wsgi </howto/deployment/wsgi/modwsgi>`
|
2010-08-28 10:40:57 +08:00
|
|
|
for information on how to configure mod_wsgi once you have it
|
|
|
|
installed.
|
|
|
|
|
2011-09-05 05:17:30 +08:00
|
|
|
If you can't use mod_wsgi for some reason, fear not: Django supports many other
|
2012-07-22 22:54:47 +08:00
|
|
|
deployment options. One is :doc:`uWSGI </howto/deployment/wsgi/uwsgi>`; it works
|
2013-07-18 23:10:49 +08:00
|
|
|
very well with `nginx`_. Additionally, Django follows the WSGI spec
|
2014-08-11 19:34:48 +08:00
|
|
|
(:pep:`3333`), which allows it to run on a variety of server platforms.
|
2005-07-16 05:51:05 +08:00
|
|
|
|
2015-11-30 00:29:46 +08:00
|
|
|
.. _Apache: https://httpd.apache.org/
|
2018-01-07 21:28:41 +08:00
|
|
|
.. _nginx: https://nginx.org/
|
2018-11-11 06:40:50 +08:00
|
|
|
.. _mod_wsgi: https://modwsgi.readthedocs.io/en/develop/
|
2005-07-16 05:51:05 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
.. _database-installation:
|
|
|
|
|
2005-07-16 05:51:05 +08:00
|
|
|
Get your database running
|
|
|
|
=========================
|
|
|
|
|
2009-06-24 22:00:53 +08:00
|
|
|
If you plan to use Django's database API functionality, you'll need to make
|
|
|
|
sure a database server is running. Django supports many different database
|
2019-05-28 01:59:49 +08:00
|
|
|
servers and is officially supported with PostgreSQL_, MariaDB_, MySQL_, Oracle_
|
|
|
|
and SQLite_.
|
2012-10-12 07:54:52 +08:00
|
|
|
|
2012-10-16 07:54:37 +08:00
|
|
|
If you are developing a simple project or something you don't plan to deploy
|
|
|
|
in a production environment, SQLite is generally the simplest option as it
|
|
|
|
doesn't require running a separate server. However, SQLite has many differences
|
|
|
|
from other databases, so if you are working on something substantial, it's
|
2018-03-05 14:12:18 +08:00
|
|
|
recommended to develop with the same database that you plan on using in
|
2012-10-16 07:54:37 +08:00
|
|
|
production.
|
2005-07-16 05:51:05 +08:00
|
|
|
|
2013-12-19 07:48:21 +08:00
|
|
|
In addition to the officially supported databases, there are :ref:`backends
|
|
|
|
provided by 3rd parties <third-party-notes>` that allow you to use other
|
|
|
|
databases with Django.
|
2009-06-24 22:00:53 +08:00
|
|
|
|
|
|
|
In addition to a database backend, you'll need to make sure your Python
|
|
|
|
database bindings are installed.
|
2005-07-19 02:47:55 +08:00
|
|
|
|
2015-02-17 03:22:22 +08:00
|
|
|
* If you're using PostgreSQL, you'll need the `psycopg2`_ package. Refer to the
|
|
|
|
:ref:`PostgreSQL notes <postgresql-notes>` for further details.
|
2007-04-26 22:58:18 +08:00
|
|
|
|
2019-05-28 01:59:49 +08:00
|
|
|
* If you're using MySQL or MariaDB, you'll need a :ref:`DB API driver
|
2015-02-17 03:22:22 +08:00
|
|
|
<mysql-db-api-drivers>` like ``mysqlclient``. See :ref:`notes for the MySQL
|
|
|
|
backend <mysql-notes>` for details.
|
2007-02-27 05:39:09 +08:00
|
|
|
|
2013-10-07 18:40:41 +08:00
|
|
|
* If you're using SQLite you might want to read the :ref:`SQLite backend notes
|
|
|
|
<sqlite-notes>`.
|
|
|
|
|
2009-02-28 14:03:18 +08:00
|
|
|
* If you're using Oracle, you'll need a copy of cx_Oracle_, but please
|
2015-02-17 03:22:22 +08:00
|
|
|
read the :ref:`notes for the Oracle backend <oracle-notes>` for details
|
|
|
|
regarding supported versions of both Oracle and ``cx_Oracle``.
|
2007-06-23 22:16:00 +08:00
|
|
|
|
2009-06-24 22:00:53 +08:00
|
|
|
* If you're using an unofficial 3rd party backend, please consult the
|
|
|
|
documentation provided for any additional requirements.
|
|
|
|
|
2013-07-25 23:19:36 +08:00
|
|
|
If you plan to use Django's ``manage.py migrate`` command to automatically
|
2012-12-17 04:42:01 +08:00
|
|
|
create database tables for your models (after first installing Django and
|
|
|
|
creating a project), you'll need to ensure that Django has permission to create
|
|
|
|
and alter tables in the database you're using; if you plan to manually create
|
|
|
|
the tables, you can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and
|
2013-07-25 23:19:36 +08:00
|
|
|
``DELETE`` permissions. After creating a database user with these
|
2012-12-17 04:42:01 +08:00
|
|
|
permissions, you'll specify the details in your project's settings file,
|
|
|
|
see :setting:`DATABASES` for details.
|
2007-12-04 14:07:44 +08:00
|
|
|
|
2012-12-22 08:59:06 +08:00
|
|
|
If you're using Django's :doc:`testing framework</topics/testing/index>` to test
|
2012-12-12 07:43:37 +08:00
|
|
|
database queries, Django will need permission to create a test database.
|
2007-09-15 12:58:41 +08:00
|
|
|
|
2016-10-25 23:43:32 +08:00
|
|
|
.. _PostgreSQL: https://www.postgresql.org/
|
2019-05-28 01:59:49 +08:00
|
|
|
.. _MariaDB: https://mariadb.org/
|
2015-11-30 00:29:46 +08:00
|
|
|
.. _MySQL: https://www.mysql.com/
|
2015-02-17 03:22:22 +08:00
|
|
|
.. _psycopg2: http://initd.org/psycopg/
|
2015-11-30 00:29:46 +08:00
|
|
|
.. _SQLite: https://www.sqlite.org/
|
2017-05-20 23:51:21 +08:00
|
|
|
.. _cx_Oracle: https://oracle.github.io/python-cx_Oracle/
|
|
|
|
.. _Oracle: https://www.oracle.com/
|
2015-09-26 03:27:41 +08:00
|
|
|
|
2008-08-26 23:52:21 +08:00
|
|
|
.. _install-django-code:
|
2007-04-12 21:59:09 +08:00
|
|
|
|
2005-07-16 05:51:05 +08:00
|
|
|
Install the Django code
|
|
|
|
=======================
|
|
|
|
|
2005-07-16 05:21:18 +08:00
|
|
|
Installation instructions are slightly different depending on whether you're
|
2008-08-24 06:25:40 +08:00
|
|
|
installing a distribution-specific package, downloading the latest official
|
2007-07-12 22:41:32 +08:00
|
|
|
release, or fetching the latest development version.
|
2005-07-16 05:21:18 +08:00
|
|
|
|
2007-07-12 22:41:32 +08:00
|
|
|
It's easy, no matter which way you choose.
|
2005-07-16 05:21:18 +08:00
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
.. _installing-official-release:
|
2007-02-27 07:23:01 +08:00
|
|
|
|
2012-03-03 17:11:54 +08:00
|
|
|
Installing an official release with ``pip``
|
2016-01-03 18:56:22 +08:00
|
|
|
-------------------------------------------
|
2012-03-03 17:11:54 +08:00
|
|
|
|
|
|
|
This is the recommended way to install Django.
|
|
|
|
|
2018-11-16 02:54:28 +08:00
|
|
|
#. Install pip_. The easiest is to use the `standalone pip installer`_. If your
|
2012-03-13 04:05:48 +08:00
|
|
|
distribution already has ``pip`` installed, you might need to update it if
|
2015-12-06 05:28:29 +08:00
|
|
|
it's outdated. If it's outdated, you'll know because installation won't
|
2016-01-24 17:06:01 +08:00
|
|
|
work.
|
2012-03-03 17:11:54 +08:00
|
|
|
|
2018-11-16 02:54:28 +08:00
|
|
|
#. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide
|
2015-09-26 03:27:41 +08:00
|
|
|
isolated Python environments, which are more practical than installing
|
|
|
|
packages systemwide. They also allow installing packages without
|
|
|
|
administrator privileges. The :doc:`contributing tutorial
|
2017-01-19 00:51:29 +08:00
|
|
|
</intro/contributing>` walks through how to create a virtualenv.
|
2012-03-03 17:11:54 +08:00
|
|
|
|
2019-02-16 14:56:28 +08:00
|
|
|
#. After you've created and activated a virtual environment, enter the command:
|
|
|
|
|
|
|
|
.. console::
|
|
|
|
|
2019-04-14 23:02:36 +08:00
|
|
|
$ python -m pip install Django
|
2012-03-03 17:11:54 +08:00
|
|
|
|
2015-08-08 19:56:37 +08:00
|
|
|
.. _pip: https://pip.pypa.io/
|
2016-11-21 23:38:30 +08:00
|
|
|
.. _virtualenv: https://virtualenv.pypa.io/
|
2016-04-28 22:09:57 +08:00
|
|
|
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/
|
2016-06-16 09:20:23 +08:00
|
|
|
.. _standalone pip installer: https://pip.pypa.io/en/latest/installing/#installing-with-get-pip-py
|
2012-03-03 17:11:54 +08:00
|
|
|
|
2017-01-10 22:29:23 +08:00
|
|
|
.. _installing-distribution-package:
|
|
|
|
|
2015-02-04 05:35:28 +08:00
|
|
|
Installing a distribution-specific package
|
2016-01-03 18:56:22 +08:00
|
|
|
------------------------------------------
|
2015-02-04 05:35:28 +08:00
|
|
|
|
|
|
|
Check the :doc:`distribution specific notes </misc/distributions>` to see if
|
|
|
|
your platform/distribution provides official Django packages/installers.
|
|
|
|
Distribution-provided packages will typically allow for automatic installation
|
|
|
|
of dependencies and easy upgrade paths; however, these packages will rarely
|
|
|
|
contain the latest release of Django.
|
|
|
|
|
2008-08-24 06:25:40 +08:00
|
|
|
.. _installing-development-version:
|
|
|
|
|
2005-07-16 05:21:18 +08:00
|
|
|
Installing the development version
|
2016-01-03 18:56:22 +08:00
|
|
|
----------------------------------
|
2005-07-16 05:21:18 +08:00
|
|
|
|
2008-03-19 07:18:52 +08:00
|
|
|
.. admonition:: Tracking Django development
|
2009-04-01 09:36:44 +08:00
|
|
|
|
2008-03-19 07:18:52 +08:00
|
|
|
If you decide to use the latest development version of Django,
|
|
|
|
you'll want to pay close attention to `the development timeline`_,
|
2012-09-10 00:53:32 +08:00
|
|
|
and you'll want to keep an eye on the :ref:`release notes for the
|
|
|
|
upcoming release <development_release_notes>`. This will help you stay
|
|
|
|
on top of any new features you might want to use, as well as any changes
|
2008-03-25 12:42:21 +08:00
|
|
|
you'll need to make to your code when updating your copy of Django.
|
|
|
|
(For stable releases, any necessary changes are documented in the
|
|
|
|
release notes.)
|
2008-03-19 07:18:52 +08:00
|
|
|
|
2012-03-14 01:53:31 +08:00
|
|
|
.. _the development timeline: https://code.djangoproject.com/timeline
|
2008-03-19 07:18:52 +08:00
|
|
|
|
2006-10-17 06:38:18 +08:00
|
|
|
If you'd like to be able to update your Django code occasionally with the
|
|
|
|
latest bug fixes and improvements, follow these instructions:
|
|
|
|
|
2018-11-16 02:54:28 +08:00
|
|
|
#. Make sure that you have Git_ installed and that you can run its commands
|
2012-04-28 11:26:16 +08:00
|
|
|
from a shell. (Enter ``git help`` at a shell prompt to test this.)
|
2007-06-20 14:23:15 +08:00
|
|
|
|
2018-11-16 02:54:28 +08:00
|
|
|
#. Check out Django's main development branch like so:
|
2008-08-24 06:25:40 +08:00
|
|
|
|
2018-01-21 01:38:48 +08:00
|
|
|
.. console::
|
2005-07-16 05:52:16 +08:00
|
|
|
|
2017-03-17 01:46:34 +08:00
|
|
|
$ git clone https://github.com/django/django.git
|
2007-09-14 16:04:07 +08:00
|
|
|
|
2015-09-26 03:27:41 +08:00
|
|
|
This will create a directory ``django`` in your current directory.
|
2011-06-27 00:52:13 +08:00
|
|
|
|
2018-11-16 02:54:28 +08:00
|
|
|
#. Make sure that the Python interpreter can load Django's code. The most
|
2015-09-26 03:27:41 +08:00
|
|
|
convenient way to do this is to use virtualenv_, virtualenvwrapper_, and
|
|
|
|
pip_. The :doc:`contributing tutorial </intro/contributing>` walks through
|
2017-01-19 00:51:29 +08:00
|
|
|
how to create a virtualenv.
|
2009-04-01 09:36:44 +08:00
|
|
|
|
2018-11-16 02:54:28 +08:00
|
|
|
#. After setting up and activating the virtualenv, run the following command:
|
2007-09-14 16:04:07 +08:00
|
|
|
|
2018-01-21 01:38:48 +08:00
|
|
|
.. console::
|
2005-07-16 05:52:16 +08:00
|
|
|
|
2019-04-14 23:02:36 +08:00
|
|
|
$ python -m pip install -e django/
|
2006-10-17 06:38:18 +08:00
|
|
|
|
2012-05-22 07:28:58 +08:00
|
|
|
This will make Django's code importable, and will also make the
|
2014-07-26 19:21:52 +08:00
|
|
|
``django-admin`` utility command available. In other words, you're all
|
2012-05-22 07:28:58 +08:00
|
|
|
set!
|
2007-11-30 00:57:20 +08:00
|
|
|
|
2006-10-17 06:38:18 +08:00
|
|
|
When you want to update your copy of the Django source code, just run the
|
2015-09-26 03:27:41 +08:00
|
|
|
command ``git pull`` from within the ``django`` directory. When you do this,
|
|
|
|
Git will automatically download any changes.
|
2005-07-16 05:21:18 +08:00
|
|
|
|
2017-05-20 23:51:21 +08:00
|
|
|
.. _Git: https://git-scm.com/
|