docs/install.txt

   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 Being a Python Web framework, Django requires Python.
  11
  12 It works with any Python version 2.3 and higher.
  13
  14 Get Python at http://www.python.org. If you're running Linux or Mac OS X, you
  15 probably already have it installed.
  16
  17 Install Apache and mod_python
  18 =============================
  19
  20 If you just want to experiment with Django, skip ahead to the next
  21 section; Django includes a lightweight Web server you can use for
  22 testing, so you won't need to set up Apache until you're ready to
  23 deploy Django in production.
  24
  25 If you want to use Django on a production site, use Apache with `mod_python`_.
  26 mod_python is similar to mod_perl -- it embeds Python within Apache and loads
  27 Python code into memory when the server starts. Code stays in memory throughout
  28 the life of an Apache process, which leads to significant performance gains
  29 over other server arrangements. Make sure you have Apache installed, with the
  30 mod_python module activated. Django requires Apache 2.x and mod_python 3.x.
  31
  32 See `How to use Django with mod_python`_ for information on how to configure
  33 mod_python once you have it installed.
  34
  35 If you can't use mod_python for some reason, fear not: Django follows the WSGI_
  36 spec, which allows it to run on a variety of server platforms. See the
  37 `server-arrangements wiki page`_ for specific installation instructions for
  38 each platform.
  39
  40 .. _Apache: http://httpd.apache.org/
  41 .. _mod_python: http://www.modpython.org/
  42 .. _WSGI: http://www.python.org/peps/pep-0333.html
  43 .. _How to use Django with mod_python: ../modpython/
  44 .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
  45
  46 Get your database running
  47 =========================
  48
  49 If you plan to use Django's database API functionality, you'll need to
  50 make sure a database server is running. Django works with PostgreSQL_,
  51 MySQL_, Oracle_ and SQLite_ (although SQLite doesn't require a separate server
  52 to be running).
  53
  54 Additionally, you'll need to make sure your Python database bindings are
  55 installed.
  56
  57 * If you're using PostgreSQL, you'll need the psycopg_ package. Django supports
  58   both version 1 and 2. (When you configure Django's database layer, specify
  59   either ``postgresql`` [for version 1] or ``postgresql_psycopg2`` [for version 2].)
  60
  61   If you're on Windows, check out the unofficial `compiled Windows version`_.
  62
  63 * If you're using MySQL, you'll need MySQLdb_, version 1.2.1p2 or higher.
  64   You will also want to read the database-specific notes for the `MySQL backend`_.
  65
  66 * If you're using SQLite and either Python 2.3 or Python 2.4, you'll need
  67   pysqlite_. Use version 2.0.3 or higher. Python 2.5 ships with an SQLite
  68   wrapper in the standard library, so you don't need to install anything extra
  69   in that case.
  70
  71 * If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher.
  72   You will also want to read the database-specific notes for the `Oracle backend`_.
  73
  74 If you plan to use Django's ``manage.py syncdb`` command to
  75 automatically create database tables for your models, you'll need to
  76 ensure that Django has permission to create and alter tables in the
  77 database you're using; if you plan to manually create the tables, you
  78 can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and
  79 ``DELETE`` permissions. On some databases, Django will need
  80 ``ALTER TABLE`` privileges during ``syncdb`` but won't issue
  81 ``ALTER TABLE`` statements on a table once ``syncdb`` has created it.
  82
  83 If you're using Django's `testing framework`_ to test database queries,
  84 Django will need permission to create a test database.
  85
  86 .. _PostgreSQL: http://www.postgresql.org/
  87 .. _MySQL: http://www.mysql.com/
  88 .. _Django's ticket system: http://code.djangoproject.com/report/1
  89 .. _psycopg: http://initd.org/tracker/psycopg
  90 .. _compiled Windows version: http://stickpeople.com/projects/python/win-psycopg/
  91 .. _MySQLdb: http://sourceforge.net/projects/mysql-python
  92 .. _SQLite: http://www.sqlite.org/
  93 .. _pysqlite: http://initd.org/tracker/pysqlite
  94 .. _MySQL backend: ../databases/
  95 .. _cx_Oracle: http://cx-oracle.sourceforge.net/
  96 .. _Oracle: http://www.oracle.com/
  97 .. _Oracle backend: ../databases/#oracle-notes
  98 .. _testing framework: ../testing/
  99
 100 Remove any old versions of Django
 101 =================================
 102
 103 If you are upgrading your installation of Django from a previous version,
 104 you will need to uninstall the old Django version before installing the
 105 new version.
 106
 107 If you installed Django using ``setup.py install``, uninstalling
 108 is as simple as deleting the ``django`` directory from your Python
 109 ``site-packages``.
 110
 111 If you installed Django from a Python egg, remove the Django ``.egg`` file,
 112 and remove the reference to the egg in the file named ``easy-install.pth``.
 113 This file should also be located in your ``site-packages`` directory.
 114
 115 .. admonition:: Where are my ``site-packages`` stored?
 116
 117     The location of the ``site-packages`` directory depends on the operating
 118     system, and the location in which Python was installed. To find out your
 119     system's ``site-packages`` location, execute the following::
 120
 121         python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
 122
 123     (Note that this should be run from a shell prompt, not a Python interactive
 124     prompt.)
 125
 126 Install the Django code
 127 =======================
 128
 129 Installation instructions are slightly different depending on whether you're
 130 installing a distribution-specific package, downloading the the latest official
 131 release, or fetching the latest development version.
 132
 133 It's easy, no matter which way you choose.
 134
 135 Installing a distribution-specific package
 136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 137
 138 Check the `distribution specific notes`_ to see if your
 139 platform/distribution provides official Django packages/installers.
 140 Distribution-provided packages will typically allow for automatic
 141 installation of dependencies and easy upgrade paths.
 142
 143 Installing an official release
 144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 145
 146     1. Download the latest release from our `download page`_.
 147
 148     2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``,
 149        where ``NNN`` is the version number of the latest release).
 150        If you're using Windows, you can download the command-line tool
 151        bsdtar_ to do this, or you can use a GUI-based tool such as 7-zip_.
 152
 153     3. Change into the directory created in step 2 (e.g. ``cd Django-NNN``).
 154
 155     4. If you're using Linux, Mac OS X or some other flavor of Unix, enter
 156        the command ``sudo python setup.py install`` at the shell prompt.
 157        If you're using Windows, start up a command shell with administrator
 158        privileges and run the command ``setup.py install``.
 159
 160 These commands will install Django in your Python installation's
 161 ``site-packages`` directory.
 162
 163 .. _distribution specific notes: ../distributions/
 164 .. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
 165 .. _7-zip: http://www.7-zip.org/
 166
 167 Installing the development version
 168 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 169
 170 .. admonition:: Tracking Django development
 171
 172     If you decide to use the latest development version of Django,
 173     you'll want to pay close attention to `the development timeline`_,
 174     and you'll want to keep an eye on `the list of
 175     backwards-incompatible changes`_. This will help you stay on top
 176     of any new features you might want to use, as well as any changes
 177     you'll need to make to your code when updating your copy of Django.
 178     (For stable releases, any necessary changes are documented in the
 179     release notes.)
 180
 181 .. _the development timeline: http://code.djangoproject.com/timeline
 182 .. _the list of backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges
 183
 184 If you'd like to be able to update your Django code occasionally with the
 185 latest bug fixes and improvements, follow these instructions:
 186
 187 1. Make sure that you have Subversion_ installed, and that you can run its
 188    commands from a shell. (Enter ``svn help`` at a shell prompt to test
 189    this.)
 190
 191 2. Check out Django's main development branch (the 'trunk') like so::
 192
 193        svn co http://code.djangoproject.com/svn/django/trunk/ django-trunk
 194
 195 3. Next, make sure that the Python interpreter can load Django's code. There
 196    are various ways of accomplishing this.  One of the most convenient, on
 197    Linux, Mac OSX or other Unix-like systems, is to use a symbolic link::
 198
 199        ln -s `pwd`/django-trunk/django SITE-PACKAGES-DIR/django
 200
 201    (In the above line, change ``SITE-PACKAGES-DIR`` to match the location of
 202    your system's ``site-packages`` directory, as explained in the
 203    "Where are my ``site-packages`` stored?" section above.)
 204
 205    Alternatively, you can define your ``PYTHONPATH`` environment variable
 206    so that it includes the ``django-trunk`` directory. This is perhaps the
 207    most convenient solution on Windows systems, which don't support symbolic
 208    links. (Environment variables can be defined on Windows systems `from the
 209    Control Panel`_.)
 210
 211    .. admonition:: What about Apache and mod_python?
 212
 213       If you take the approach of setting ``PYTHONPATH``, you'll need to
 214       remember to do the same thing in your Apache configuration once you
 215       deploy your production site. Do this by setting ``PythonPath`` in your
 216       Apache configuration file.
 217
 218       More information about deployment is available, of course, in our
 219       `How to use Django with mod_python`_ documentation.
 220
 221       .. _How to use Django with mod_python: ../modpython/
 222
 223 4. On Unix-like systems, create a symbolic link to the file
 224    ``django-trunk/django/bin/django-admin.py`` in a directory on your system
 225    path, such as ``/usr/local/bin``. For example::
 226
 227        ln -s `pwd`/django-trunk/django/bin/django-admin.py /usr/local/bin
 228
 229    This simply lets you type ``django-admin.py`` from within any directory,
 230    rather than having to qualify the command with the full path to the file.
 231
 232    On Windows systems, the same result can be achieved by copying the file
 233    ``django-trunk/django/bin/django-admin.py`` to somewhere on your system
 234    path, for example ``C:\Python24\Scripts``.
 235
 236 You *don't* have to run ``python setup.py install``, because you've already
 237 carried out the equivalent actions in steps 3 and 4.
 238
 239 When you want to update your copy of the Django source code, just run the
 240 command ``svn update`` from within the ``django-trunk`` directory. When you do
 241 this, Subversion will automatically download any changes.
 242
 243 .. _`download page`: http://www.djangoproject.com/download/
 244 .. _Subversion: http://subversion.tigris.org/
 245 .. _from the Control Panel: http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/sysdm_advancd_environmnt_addchange_variable.mspx