/docs/topics/install.txt

  1=====================
  2How to install Django
  3=====================
  4
  5This document will get you up and running with Django.
  6
  7Install Python
  8==============
  9
 10Being a Python Web framework, Django requires Python.
 11
 12It works with any Python version from 2.4 to 2.7 (due to backwards
 13incompatibilities in Python 3.0, Django does not currently work with
 14Python 3.0; see :doc:`the Django FAQ </faq/install>` for more
 15information on supported Python versions and the 3.0 transition).
 16
 17Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
 18probably already have it installed.
 19
 20.. admonition:: Django on Jython
 21
 22    If you use Jython_ (a Python implementation for the Java platform), you'll
 23    need to follow a few additional steps. See :doc:`/howto/jython` for details.
 24
 25.. _jython: http://jython.org/
 26
 27Install Apache and mod_wsgi
 28=============================
 29
 30If you just want to experiment with Django, skip ahead to the next
 31section; Django includes a lightweight Web server you can use for
 32testing, so you won't need to set up Apache until you're ready to
 33deploy Django in production.
 34
 35If you want to use Django on a production site, use Apache with
 36`mod_wsgi`_. mod_wsgi can operate in one of two modes: an embedded
 37mode and a daemon mode. In embedded mode, mod_wsgi is similar to
 38mod_perl -- it embeds Python within Apache and loads Python code into
 39memory when the server starts. Code stays in memory throughout the
 40life of an Apache process, which leads to significant performance
 41gains over other server arrangements. In daemon mode, mod_wsgi spawns
 42an independent daemon process that handles requests. The daemon
 43process can run as a different user than the Web server, possibly
 44leading to improved security, and the daemon process can be restarted
 45without restarting the entire Apache Web server, possibly making
 46refreshing your codebase more seamless. Consult the mod_wsgi
 47documentation to determine which mode is right for your setup. Make
 48sure you have Apache installed, with the mod_wsgi module activated.
 49Django will work with any version of Apache that supports mod_wsgi.
 50
 51See :doc:`How to use Django with mod_wsgi </howto/deployment/modwsgi>`
 52for information on how to configure mod_wsgi once you have it
 53installed.
 54
 55If you can't use mod_wsgi for some reason, fear not: Django supports
 56many other deployment options. Another option is :doc:`FastCGI
 57</howto/deployment/fastcgi>`, perfect for using Django with servers
 58other than Apache. Additionally, Django follows the WSGI_ spec, which
 59allows it to run on a variety of server platforms. See the
 60`server-arrangements wiki page`_ for specific installation
 61instructions for each platform.
 62
 63.. _Apache: http://httpd.apache.org/
 64.. _mod_wsgi: http://code.google.com/p/modwsgi/
 65.. _WSGI: http://www.python.org/dev/peps/pep-0333/
 66.. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
 67
 68.. _database-installation:
 69
 70Get your database running
 71=========================
 72
 73If you plan to use Django's database API functionality, you'll need to make
 74sure a database server is running. Django supports many different database
 75servers and is officially supported with PostgreSQL_, MySQL_, Oracle_ and
 76SQLite_ (although SQLite doesn't require a separate server to be running).
 77
 78In addition to the officially supported databases, there are backends provided
 79by 3rd parties that allow you to use other databases with Django:
 80
 81* `Sybase SQL Anywhere`_
 82* `IBM DB2`_
 83* `Microsoft SQL Server 2005`_
 84* Firebird_
 85* ODBC_
 86
 87The Django versions and ORM features supported by these unofficial backends
 88vary considerably. Queries regarding the specific capabilities of these
 89unofficial backends, along with any support queries, should be directed to the
 90support channels provided by each 3rd party project.
 91
 92In addition to a database backend, you'll need to make sure your Python
 93database bindings are installed.
 94
 95* If you're using PostgreSQL, you'll need the psycopg_ package. Django supports
 96  both version 1 and 2. (When you configure Django's database layer, specify
 97  either ``postgresql`` [for version 1] or ``postgresql_psycopg2`` [for version 2].)
 98  You might want to refer to our :ref:`PostgreSQL notes <postgresql-notes>` for
 99  further technical details specific to this database.
100
101  If you're on Windows, check out the unofficial `compiled Windows version`_.
102
103* If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher. You
104  will also want to read the database-specific :ref:`notes for the MySQL
105  backend <mysql-notes>`.
106
107* If you're using SQLite and Python 2.4, you'll need pysqlite_. Use version
108  2.0.3 or higher. Python 2.5 ships with an SQLite wrapper in the standard
109  library, so you don't need to install anything extra in that case. Please
110  read the :ref:`SQLite backend notes <sqlite-notes>`.
111
112* If you're using Oracle, you'll need a copy of cx_Oracle_, but please
113  read the database-specific :ref:`notes for the Oracle backend <oracle-notes>`
114  for important information regarding supported versions of both Oracle and
115  ``cx_Oracle``.
116
117* If you're using an unofficial 3rd party backend, please consult the
118  documentation provided for any additional requirements.
119
120If you plan to use Django's ``manage.py syncdb`` command to
121automatically create database tables for your models, you'll need to
122ensure that Django has permission to create and alter tables in the
123database you're using; if you plan to manually create the tables, you
124can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and
125``DELETE`` permissions. On some databases, Django will need
126``ALTER TABLE`` privileges during ``syncdb`` but won't issue
127``ALTER TABLE`` statements on a table once ``syncdb`` has created it.
128
129If you're using Django's :doc:`testing framework</topics/testing>` to test database queries,
130Django will need permission to create a test database.
131
132.. _PostgreSQL: http://www.postgresql.org/
133.. _MySQL: http://www.mysql.com/
134.. _psycopg: http://initd.org/pub/software/psycopg/
135.. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
136.. _MySQLdb: http://sourceforge.net/projects/mysql-python
137.. _SQLite: http://www.sqlite.org/
138.. _pysqlite: http://trac.edgewall.org/wiki/PySqlite
139.. _cx_Oracle: http://cx-oracle.sourceforge.net/
140.. _Oracle: http://www.oracle.com/
141.. _Sybase SQL Anywhere: http://code.google.com/p/sqlany-django/
142.. _IBM DB2: http://code.google.com/p/ibm-db/
143.. _Microsoft SQL Server 2005: http://code.google.com/p/django-mssql/
144.. _Firebird: http://code.google.com/p/django-firebird/
145.. _ODBC: http://code.google.com/p/django-pyodbc/
146.. _removing-old-versions-of-django:
147
148Remove any old versions of Django
149=================================
150
151If you are upgrading your installation of Django from a previous version,
152you will need to uninstall the old Django version before installing the
153new version.
154
155If you installed Django using ``setup.py install``, uninstalling
156is as simple as deleting the ``django`` directory from your Python
157``site-packages``.
158
159If you installed Django from a Python egg, remove the Django ``.egg`` file,
160and remove the reference to the egg in the file named ``easy-install.pth``.
161This file should also be located in your ``site-packages`` directory.
162
163.. _finding-site-packages:
164
165.. admonition:: Where are my ``site-packages`` stored?
166
167    The location of the ``site-packages`` directory depends on the operating
168    system, and the location in which Python was installed. To find out your
169    system's ``site-packages`` location, execute the following:
170
171    .. code-block:: bash
172
173        python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
174
175    (Note that this should be run from a shell prompt, not a Python interactive
176    prompt.)
177
178.. _install-django-code:
179
180Install the Django code
181=======================
182
183Installation instructions are slightly different depending on whether you're
184installing a distribution-specific package, downloading the latest official
185release, or fetching the latest development version.
186
187It's easy, no matter which way you choose.
188
189Installing a distribution-specific package
190~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
191
192Check the :doc:`distribution specific notes </misc/distributions>` to see if your
193platform/distribution provides official Django packages/installers.
194Distribution-provided packages will typically allow for automatic installation
195of dependencies and easy upgrade paths.
196
197.. _installing-official-release:
198
199Installing an official release
200~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
201
202    1. Download the latest release from our `download page`_.
203
204    2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``,
205       where ``NNN`` is the version number of the latest release).
206       If you're using Windows, you can download the command-line tool
207       bsdtar_ to do this, or you can use a GUI-based tool such as 7-zip_.
208
209    3. Change into the directory created in step 2 (e.g. ``cd Django-NNN``).
210
211    4. If you're using Linux, Mac OS X or some other flavor of Unix, enter
212       the command ``sudo python setup.py install`` at the shell prompt.
213       If you're using Windows, start up a command shell with administrator
214       privileges and run the command ``setup.py install``.
215
216These commands will install Django in your Python installation's
217``site-packages`` directory.
218
219.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
220.. _7-zip: http://www.7-zip.org/
221
222.. _installing-development-version:
223
224Installing the development version
225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226
227.. admonition:: Tracking Django development
228
229    If you decide to use the latest development version of Django,
230    you'll want to pay close attention to `the development timeline`_,
231    and you'll want to keep an eye on `the list of
232    backwards-incompatible changes`_. This will help you stay on top
233    of any new features you might want to use, as well as any changes
234    you'll need to make to your code when updating your copy of Django.
235    (For stable releases, any necessary changes are documented in the
236    release notes.)
237
238.. _the development timeline: http://code.djangoproject.com/timeline
239.. _the list of backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
240
241If you'd like to be able to update your Django code occasionally with the
242latest bug fixes and improvements, follow these instructions:
243
2441. Make sure that you have Subversion_ installed, and that you can run its
245   commands from a shell. (Enter ``svn help`` at a shell prompt to test
246   this.)
247
2482. Check out Django's main development branch (the 'trunk') like so:
249
250   .. code-block:: bash
251
252       svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk
253
2543. Next, make sure that the Python interpreter can load Django's code. The most
255   convenient way to do this is to `modify Python's search path`_. Add a ``.pth``
256   file containing the full path to the ``django-trunk`` directory to your
257   system's ``site-packages`` directory. For example, on a Unix-like system:
258
259   .. code-block:: bash
260
261       echo WORKING-DIR/django-trunk > SITE-PACKAGES-DIR/django.pth
262
263   (In the above line, change ``SITE-PACKAGES-DIR`` to match the location of
264   your system's ``site-packages`` directory, as explained in the
265   :ref:`Where are my site-packages stored? <finding-site-packages>` section
266   above. Change ``WORKING-DIR/django-trunk`` to match the full path to your
267   new ``django-trunk`` directory.)
268
2694. On Unix-like systems, create a symbolic link to the file
270   ``django-trunk/django/bin/django-admin.py`` in a directory on your system
271   path, such as ``/usr/local/bin``. For example:
272
273   .. code-block:: bash
274
275       ln -s WORKING-DIR/django-trunk/django/bin/django-admin.py /usr/local/bin
276
277   (In the above line, change WORKING-DIR to match the full path to your new
278   ``django-trunk`` directory.)
279
280   This simply lets you type ``django-admin.py`` from within any directory,
281   rather than having to qualify the command with the full path to the file.
282
283   On Windows systems, the same result can be achieved by copying the file
284   ``django-trunk/django/bin/django-admin.py`` to somewhere on your system
285   path, for example ``C:\Python24\Scripts``.
286
287You *don't* have to run ``python setup.py install``, because you've already
288carried out the equivalent actions in steps 3 and 4.
289
290When you want to update your copy of the Django source code, just run the
291command ``svn update`` from within the ``django-trunk`` directory. When you do
292this, Subversion will automatically download any changes.
293
294.. _`download page`: http://www.djangoproject.com/download/
295.. _Subversion: http://subversion.tigris.org/
296.. _`modify Python's search path`: http://docs.python.org/install/index.html#modifying-python-s-search-path