Installing Pylons
+++++++++++++++++

First, please note that Python 2.3 users on Windows will need to install `subprocess.exe <http://www.pylonshq.com/download/subprocess-0.1-20041012.win32-py2.3.exe>`_ before beginning the installation (whereas Python 2.4 users on Windows do not). All windows users also should read the section `Post install tweaks for Windows <windowsnotes.html>`_ after installation. Users of Ubuntu/debian will also likely need to install the python-dev package.

System-wide Install
===================

To install Pylons so it can be used by everyone (you'll need root access).

If you already have easy install::

    easy_install Pylons

.. Note::
    On rare occasions, the python.org Cheeseshop goes down. It is still 
    possible to install Pylons and its dependencies however by specifying our
    local package directory for installation with:
    
        ``easy_install -f http://pylonshq.com/download/ Pylons``
    
    Which will use the packages necessary for the latest release. If you're 
    using an older version of Pylons, you can get the packages that went with
    it by specifying the version desired:
    
        ``easy_install -f http://pylonshq.com/download/0.8.2/ Pylons``

Otherwise: 

#. Download the easy install setup file from http://peak.telecommunity.com/dist/ez_setup.py
#. Run ``python ez_setup.py Pylons``

.. Note::
   You may optionally install (or upgrade to at a later date) one of the following 'extras', by specifying the extra name in the command:

         ``easy_install Pylons[extra]``

   ``pudge``:   Support for building documentation, see `Adding Documentation to your Application <adding_docs.html>`_. Be aware that some of the documentation tools are under development and may not be stable

   ``genshi``: Support for rendering genshi templates, see `Using Other Template Languages <template_plugins.html>`_

   ``cheetah``: Support for rendering cheetah templates, see `Using Other Template Languages <template_plugins.html>`_

   ``kid``:     Support for rendering kid templates, see `Using Other Template Languages <template_plugins.html>`_

   ``full``:    All of the above

Custom Install Location
=======================

If you'd like to use a `custom installation location <http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations>`_, follow the steps there, then install Pylons as shown above. Reading the `Easy Install documentation <http://peak.telecommunity.com/DevCenter/EasyInstall>`_ can be useful to determine if you'd prefer system-wide
installation or not.

Upgrading
=========

To upgrade to the latest version of Pylons run::

    easy_install -U Pylons


Living on the Cutting Edge
==========================

Not satisfied with the latest release? Want to be on the cutting edge or work with Pylons source code?
Feel free to `get involved </project/>`_ with Pylons and work with the `latest development version <pylonsdev.html>`_.


Easy Install Problems
=====================

Occasionally Easy Install fails to find a package it is looking for or a new version of a package which Pylons depends on is released which doesn't install correctly. In this situation ensure you have the latest version of ``setuptools`` by running::

    easy_install -U setuptools
    
Try to install Pylons again and if one of the dependencies still fails you should easy_install a working version of the package manually before installing Pylons. 

As an example, if say you had a problem installing Myghty you could specify a location where easy_install should look for the latest version::

    easy_install -U -f http://pylonshq.com/download/ Myghty

Alternatively you could easy_install Myghty directly by specifying the URL of the distribution you want to install. In this case we are installing Myghty 1.1 from the cheeseshop, but you will need to install the appropriate file for the version of Pylons you are using::

    easy_install -U http://cheeseshop.python.org/packages/source/M/Myghty/Myghty-1.1.tar.gz#md5=5865361811dca4054f1ec60ac32ee965


Packaging Note
==============

The versions of Cheetah, docutils, elementtree, nose and just about everything else used by Pylons have been slightly modified by James Gardner so that they support setuptools and Python 2.3 and can automatically be installed by easy_install. Some of these packages have installation instructions which might require manual tweaking. If you plan to use the packages outside Pylons you may prefer to install them manually yourself to be 100% confident that they are setup correctly although the Pylons team haven't spotted any problems yet and they appear to work perfectly.
