245 lines
9.8 KiB
Plaintext
245 lines
9.8 KiB
Plaintext
=====================
|
|
How to install Django
|
|
=====================
|
|
|
|
This document will get you up and running with Django.
|
|
|
|
Install Python
|
|
==============
|
|
|
|
Being a Python Web framework, Django requires Python. See
|
|
:ref:`faq-python-version-support` for details.
|
|
|
|
Get the latest version of Python at https://www.python.org/download/ or with
|
|
your operating system's package manager.
|
|
|
|
.. admonition:: Django on Jython
|
|
|
|
If you use Jython_ (a Python implementation for the Java platform), you'll
|
|
need to follow a few additional steps. See :doc:`/howto/jython` for details.
|
|
|
|
.. _jython: http://jython.org/
|
|
|
|
.. admonition:: Python on Windows
|
|
|
|
If you are just starting with Django and using Windows, you may find
|
|
:doc:`/howto/windows` useful.
|
|
|
|
Install Apache and ``mod_wsgi``
|
|
===============================
|
|
|
|
If you just want to experiment with Django, skip ahead to the next
|
|
section; Django includes a lightweight web server you can use for
|
|
testing, so you won't need to set up Apache until you're ready to
|
|
deploy Django in production.
|
|
|
|
If you want to use Django on a production site, use `Apache`_ with
|
|
`mod_wsgi`_. mod_wsgi can operate in one of two modes: an embedded
|
|
mode and a daemon mode. In embedded mode, mod_wsgi is similar to
|
|
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
|
|
process can run as a different user than the Web server, possibly
|
|
leading to improved security, and the daemon process can be restarted
|
|
without restarting the entire Apache Web server, possibly making
|
|
refreshing your codebase more seamless. Consult the mod_wsgi
|
|
documentation to determine which mode is right for your setup. Make
|
|
sure you have Apache installed, with the mod_wsgi module activated.
|
|
Django will work with any version of Apache that supports mod_wsgi.
|
|
|
|
See :doc:`How to use Django with mod_wsgi </howto/deployment/wsgi/modwsgi>`
|
|
for information on how to configure mod_wsgi once you have it
|
|
installed.
|
|
|
|
If you can't use mod_wsgi for some reason, fear not: Django supports many other
|
|
deployment options. One is :doc:`uWSGI </howto/deployment/wsgi/uwsgi>`; it works
|
|
very well with `nginx`_. Additionally, Django follows the WSGI spec
|
|
(:pep:`3333`), which allows it to run on a variety of server platforms.
|
|
|
|
.. _Apache: https://httpd.apache.org/
|
|
.. _nginx: http://nginx.org/
|
|
.. _mod_wsgi: http://www.modwsgi.org/
|
|
|
|
.. _database-installation:
|
|
|
|
Get your database running
|
|
=========================
|
|
|
|
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
|
|
servers and is officially supported with PostgreSQL_, MySQL_, Oracle_ and
|
|
SQLite_.
|
|
|
|
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
|
|
recommended to develop with the same database as you plan on using in
|
|
production.
|
|
|
|
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.
|
|
|
|
In addition to a database backend, you'll need to make sure your Python
|
|
database bindings are installed.
|
|
|
|
* If you're using PostgreSQL, you'll need the `psycopg2`_ package. Refer to the
|
|
:ref:`PostgreSQL notes <postgresql-notes>` for further details.
|
|
|
|
* If you're using MySQL, you'll need a :ref:`DB API driver
|
|
<mysql-db-api-drivers>` like ``mysqlclient``. See :ref:`notes for the MySQL
|
|
backend <mysql-notes>` for details.
|
|
|
|
* If you're using SQLite you might want to read the :ref:`SQLite backend notes
|
|
<sqlite-notes>`.
|
|
|
|
* If you're using Oracle, you'll need a copy of cx_Oracle_, but please
|
|
read the :ref:`notes for the Oracle backend <oracle-notes>` for details
|
|
regarding supported versions of both Oracle and ``cx_Oracle``.
|
|
|
|
* If you're using an unofficial 3rd party backend, please consult the
|
|
documentation provided for any additional requirements.
|
|
|
|
If you plan to use Django's ``manage.py migrate`` command to automatically
|
|
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
|
|
``DELETE`` permissions. After creating a database user with these
|
|
permissions, you'll specify the details in your project's settings file,
|
|
see :setting:`DATABASES` for details.
|
|
|
|
If you're using Django's :doc:`testing framework</topics/testing/index>` to test
|
|
database queries, Django will need permission to create a test database.
|
|
|
|
.. _PostgreSQL: http://www.postgresql.org/
|
|
.. _MySQL: https://www.mysql.com/
|
|
.. _psycopg2: http://initd.org/psycopg/
|
|
.. _SQLite: https://www.sqlite.org/
|
|
.. _cx_Oracle: http://cx-oracle.sourceforge.net/
|
|
.. _Oracle: http://www.oracle.com/
|
|
|
|
.. _removing-old-versions-of-django:
|
|
|
|
Remove any old versions of Django
|
|
=================================
|
|
|
|
If you are upgrading your installation of Django from a previous version,
|
|
you will need to uninstall the old Django version before installing the
|
|
new version.
|
|
|
|
If you installed Django using pip_ or ``easy_install`` previously, installing
|
|
with pip_ or ``easy_install`` again will automatically take care of the old
|
|
version, so you don't need to do it yourself.
|
|
|
|
If you previously installed Django using ``python setup.py install``,
|
|
uninstalling is as simple as deleting the ``django`` directory from your Python
|
|
``site-packages``. To find the directory you need to remove, you can run the
|
|
following at your shell prompt (not the interactive Python prompt):
|
|
|
|
.. code-block:: console
|
|
|
|
$ python -c "import django; print(django.__path__)"
|
|
|
|
.. _install-django-code:
|
|
|
|
Install the Django code
|
|
=======================
|
|
|
|
Installation instructions are slightly different depending on whether you're
|
|
installing a distribution-specific package, downloading the latest official
|
|
release, or fetching the latest development version.
|
|
|
|
It's easy, no matter which way you choose.
|
|
|
|
.. _installing-official-release:
|
|
|
|
Installing an official release with ``pip``
|
|
-------------------------------------------
|
|
|
|
This is the recommended way to install Django.
|
|
|
|
1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
|
|
distribution already has ``pip`` installed, you might need to update it if
|
|
it's outdated. If it's outdated, you'll know because installation won't
|
|
work.
|
|
|
|
2. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide
|
|
isolated Python environments, which are more practical than installing
|
|
packages systemwide. They also allow installing packages without
|
|
administrator privileges. The :doc:`contributing tutorial
|
|
</intro/contributing>` walks through how to create a virtualenv on Python 3.
|
|
|
|
3. After you've created and activated a virtual environment, enter the command
|
|
``pip install Django`` at the shell prompt.
|
|
|
|
.. _pip: https://pip.pypa.io/
|
|
.. _virtualenv: http://www.virtualenv.org/
|
|
.. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/
|
|
.. _standalone pip installer: https://pip.pypa.io/en/latest/installing.html#install-pip
|
|
|
|
Installing a distribution-specific package
|
|
------------------------------------------
|
|
|
|
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.
|
|
|
|
.. _installing-development-version:
|
|
|
|
Installing the development version
|
|
----------------------------------
|
|
|
|
.. admonition:: Tracking Django development
|
|
|
|
If you decide to use the latest development version of Django,
|
|
you'll want to pay close attention to `the development timeline`_,
|
|
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
|
|
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.)
|
|
|
|
.. _the development timeline: https://code.djangoproject.com/timeline
|
|
|
|
If you'd like to be able to update your Django code occasionally with the
|
|
latest bug fixes and improvements, follow these instructions:
|
|
|
|
1. Make sure that you have Git_ installed and that you can run its commands
|
|
from a shell. (Enter ``git help`` at a shell prompt to test this.)
|
|
|
|
2. Check out Django's main development branch like so:
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone git://github.com/django/django.git
|
|
|
|
This will create a directory ``django`` in your current directory.
|
|
|
|
3. Make sure that the Python interpreter can load Django's code. The most
|
|
convenient way to do this is to use virtualenv_, virtualenvwrapper_, and
|
|
pip_. The :doc:`contributing tutorial </intro/contributing>` walks through
|
|
how to create a virtualenv on Python 3.
|
|
|
|
4. After setting up and activating the virtualenv, run the following command:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip install -e django/
|
|
|
|
This will make Django's code importable, and will also make the
|
|
``django-admin`` utility command available. In other words, you're all
|
|
set!
|
|
|
|
When you want to update your copy of the Django source code, just run the
|
|
command ``git pull`` from within the ``django`` directory. When you do this,
|
|
Git will automatically download any changes.
|
|
|
|
.. _Git: http://git-scm.com/
|