= setuptools
[[PageOutline(2-5, Contents, pullout)]]

[http://peak.telecommunity.com/DevCenter/setuptools setuptools] is a Python module that helps to compile, distribute and install Python packages by packaging them into "egg"s. Eggs contain additional information to process dependencies, etc. The setuptools package is required for installing Trac.

== Check your setuptools version

The version of your setuptools installation can be checked with the following commands (should work for other Python packages too):
{{{#!sh
$ python
Python 2.3.5
>>> import setuptools
>>> setuptools.__version__ 
'0.7a1' 
}}}

== Install setuptools

Setuptools can be installed using the bootstrap script from the [pypi: Python Package Indexer] ([pypi:setuptools#installation-instructions installation instructions]):
{{{#!sh
$ wget https://bootstrap.pypa.io/ez_setup.py -O - | python
}}}

Notes:
 - Do not use setuptools prior to version **0.6c10**. If you are, look for the notes in an [./@9 earlier version] of this page.
 - If you're using Python 2.4 (still supported for 0.12-stable) or Python 2.5, you won't be able to use a recent version of setuptools. You can still install an earlier version:
    - grab and execute the older [http://peak.telecommunity.com/dist/ez_setup.py ez_setup.py] script, you'll then have 0.6c11, which is enough if you're installing from a Trac checkout made with Subversion 1.6, but is problematic for newer Subversion versions.
    - with easy_install from 0.6c11, install the latest Python 2.4/2.5 compatible version of the new setuptools: `easy_install -U setuptools==1.4.2`
    - Windows users will need to add the `Scripts` directory of their Python installation (for example, `C:\Python27\Scripts`) to their `PATH` environment variable, or use the full path to `easy_install` (for example, `C:\Python27\Scripts\easy_install.py`). See [http://peak.telecommunity.com/DevCenter/EasyInstall#windows-notes Windows notes] for more information.

 - if you're using setuptools versions **5.4** through **5.6**, the environment variable `PKG_RESOURCES_CACHE_ZIP_MANIFESTS` should be set, otherwise the performance of Trac will be significantly degraded.
  - Linux: `$ export PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1`
  - Windows: `> set PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1`  
 More details can be found in TracInstall#DeployingTrac.

== Install Trac using `easy_install`

setuptools includes the `easy_install` script for convenient installation of packages found on [pypi:setuptools/ Python Package Index] including Trac with all necessary dependencies.

{{{#!sh
$ python -m easy_install Trac
}}}

''You will need root permissions or equivalent (e.g. sudo) for this step.''

{{{#!div style="border: 1pt dotted; margin: 1em"
**Note**: `pip` is a modern package installer that was developed as a replacement for `easy_install`, which you should use instead if it's available for your platform. See TracInstall for more information.
}}}

If you are working behind a proxy, note that easy_install will rely on environment variables, such as http_proxy, https_proxy, ftp_proxy.

== Install Trac from source using `easy_install`

You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. `Trac-1.0.tar.gz`) from the [trac:TracDownload] page, or you can get the source directly from the repository. See [trac:TracRepositories#OfficialSubversionrepository TracRepositories] for details.

{{{#!sh
$ python ./setup.py install
}}}

This will byte-compile the Python source code and install it as an .egg file or folder in the `site-packages` directory
of your Python installation. The .egg will also contain all other resources needed by standard Trac, such as `htdocs` and `templates`.

If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the `install` (or simply redo the `install` once again afterwards if you realize Babel was not yet installed):
{{{#!sh
$ python ./setup.py install
}}}
Alternatively, you can run `bdist_egg` and copy the .egg from `dist/` to the place of your choice, or you can create a Windows installer (`bdist_wininst`).

== Advanced `easy_install` Options

To install Trac to a custom location, or find out about other advanced installation options, run:
{{{#!sh
$ easy_install --help
}}}

Also see [http://docs.python.org/2/install/index.html Installing Python Modules] for detailed information.

Specifically, you might be interested in:
{{{#!sh
$ easy_install --prefix=/path/to/installdir
}}}
or, if installing Trac on a Mac OS X system:
{{{#!sh
$ easy_install --prefix=/usr/local --install-dir=/Library/Python/2.7/site-packages
}}}

On Mac OSX, running `easy_install trac` will install into `/usr/local` and `/Library/Python/2.7/site-packages` by default.

The `tracd` and `trac-admin` commands will be placed in `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.7/site-packages`, which is Apple's preferred location for third-party Python application installations.

== Reference Documentation

- [https://setuptools.readthedocs.io/en/latest/setuptools.html setuptools]
- [https://setuptools.readthedocs.io/en/latest/pkg_resources.html pkg_resources] (setuptools)
- [https://setuptools.readthedocs.io/en/latest/formats.html .egg format]

----
See also: TracDev/Proposals/Setuptools