/docs/topics/install.txt

https://code.google.com/p/mango-py/ · Plain Text · 296 lines · 219 code · 77 blank · 0 comment · 0 complexity · a7cd372c0eed547ed5fd7359e4ca9ae3 MD5 · raw file

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