Debian Codegraph @

docs/topics/install.txt

raw
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/