<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"inst.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"inst.html" title='Installing Python Modules'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"config-syntax.html" />
<link rel=
"prev" href=
"alt-install-windows.html" />
<link rel=
"parent" href=
"inst.html" />
<link rel=
"next" href=
"config-syntax.html" />
<meta name='aesop' content='information'
/>
<title>4 Custom Installation
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"3 Alternate Installation"
href=
"alt-install-windows.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"Installing Python Modules"
href=
"inst.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"5 Distutils Configuration Files"
href=
"config-syntax.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Installing Python Modules
</td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"alt-install-windows.html">3 Alternate Installation
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"inst.html">Installing Python Modules
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"config-syntax.html">5 Distutils Configuration Files
</A>
<!--End of Navigation Panel-->
<div class='online-navigation'
>
<!--Table of Child-Links-->
<A NAME=
"CHILD_LINKS"><STRONG>Subsections
</STRONG></a>
<LI><A href=
"search-path.html#SECTION000410000000000000000">4.1 Modifying Python's Search Path
</a>
<!--End of Table of Child-Links-->
<H1><A NAME=
"SECTION000400000000000000000"></A>
<A NAME=
"custom-install"></A>
Sometimes, the alternate installation schemes described in
section
<A href=
"alt-install-windows.html#alt-install">3</A> just don't do what you want. You might
want to tweak just one or two directories while keeping everything under
the same base directory, or you might want to completely redefine the
installation scheme. In either case, you're creating a
<em>custom
installation scheme
</em>.
You probably noticed the column of ``override options'' in the tables
describing the alternate installation schemes above. Those options are
how you define a custom installation scheme. These override options can
be relative, absolute, or explicitly defined in terms of one of the
installation base directories. (There are two installation base
directories, and they are normally the same--they only differ when you
use the
<span class=
"Unix">Unix
</span> ``prefix scheme'' and supply different
<b class=
"programopt">--prefix
</b> and
<b class=
"programopt">--exec-prefix
</b> options.)
For example, say you're installing a module distribution to your home
directory under
<span class=
"Unix">Unix
</span>--but you want scripts to go in
<span class=
"file">~/scripts
</span> rather than
<span class=
"file">~/bin
</span>.
As you might expect, you can override this directory with the
<b class=
"programopt">--install-scripts
</b> option; in this case, it makes most
sense to supply a relative path, which will be interpreted relative to
the installation base directory (your home directory, in this case):
<div class=
"verbatim"><pre>
python setup.py install --home=~ --install-scripts=scripts
Another
<span class=
"Unix">Unix
</span> example: suppose your Python installation was built and
installed with a prefix of
<span class=
"file">/usr/local/python
</span>, so under a standard
installation scripts will wind up in
<span class=
"file">/usr/local/python/bin
</span>. If
you want them in
<span class=
"file">/usr/local/bin
</span> instead, you would supply this
absolute directory for the
<b class=
"programopt">--install-scripts
</b> option:
<div class=
"verbatim"><pre>
python setup.py install --install-scripts=/usr/local/bin
(This performs an installation using the ``prefix scheme,'' where the
prefix is whatever your Python interpreter was installed with--
<span class=
"file">/usr/local/python
</span> in this case.)
If you maintain Python on Windows, you might want third-party modules to
live in a subdirectory of
<span class=
"du-filevar">prefix
</span>, rather than right in
<span class=
"du-filevar">prefix
</span> itself. This is almost as easy as customizing the
script installation directory--you just have to remember that there are
two types of modules to worry about, pure modules and non-pure modules
(i.e., modules from a non-pure distribution). For example:
<div class=
"verbatim"><pre>
python setup.py install --install-purelib=Site --install-platlib=Site
The specified installation directories are relative to
<span class=
"du-filevar">prefix
</span>. Of course, you also have to ensure that these
directories are in Python's module search path, such as by putting a
<span class=
"file">.pth
</span> file in
<span class=
"du-filevar">prefix
</span>. See section
<A HREF=
"#search-path">4.1</A>
to find out how to modify Python's search path.
If you want to define an entire installation scheme, you just have to
supply all of the installation directory options. The recommended way
to do this is to supply relative paths; for example, if you want to
maintain all Python module-related files under
<span class=
"file">python
</span> in your
home directory, and you want a separate directory for each platform that
you use your home directory from, you might define the following
<div class=
"verbatim"><pre>
python setup.py install --home=~ \
--install-purelib=python/lib \
--install-platlib=python/lib.$PLAT \
--install-scripts=python/scripts
--install-data=python/data
<div class=
"verbatim"><pre>
python setup.py install --home=~/python \
--install-platlib='lib.$PLAT' \
--install-scripts=scripts
<code>$PLAT
</code> is not (necessarily) an environment variable--it will be
expanded by the Distutils as it parses your command line options, just
as it does when parsing your configuration file(s).
Obviously, specifying the entire installation scheme every time you
install a new module distribution would be very tedious. Thus, you can
put these options into your Distutils config file (see
section
<A href=
"config-syntax.html#config-files">5</A>):
<div class=
"verbatim"><pre>
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
<div class=
"verbatim"><pre>
install-base=$HOME/python
install-platlib=lib.$PLAT
Note that these two are
<em>not
</em> equivalent if you supply a different
installation base directory when you run the setup script. For example,
<div class=
"verbatim"><pre>
python setup.py --install-base=/tmp
would install pure modules to
<span class=
"du-filevar">/tmp/python/lib
</span> in the first
case, and to
<span class=
"du-filevar">/tmp/lib
</span> in the second case. (For the second
case, you probably want to supply an installation base of
<span class=
"file">/tmp/python
</span>.)
You probably noticed the use of
<code>$HOME
</code> and
<code>$PLAT
</code> in the
sample configuration file input. These are Distutils configuration
variables, which bear a strong resemblance to environment variables.
In fact, you can use environment variables in config files on
platforms that have such a notion but the Distutils additionally
define a few extra variables that may not be in your environment, such
as
<code>$PLAT
</code>. (And of course, on systems that don't have
environment variables, such as Mac OS
9, the configuration
variables supplied by the Distutils are the only ones you can use.)
See section
<A href=
"config-syntax.html#config-files">5</A> for details.
<H2><A NAME=
"SECTION000410000000000000000"></A>
<A NAME=
"search-path"></A>
4.1 Modifying Python's Search Path
When the Python interpreter executes an
<tt class=
"keyword">import
</tt> statement, it
searches for both Python code and extension modules along a search
path. A default value for the path is configured into the Python
binary when the interpreter is built. You can determine the path by
importing the
<tt class=
"module">sys
</tt> module and printing the value of
<div class=
"verbatim"><pre>
Python
2.2 (#
11, Oct
3 2002,
13:
31:
27)
[GCC
2.96 20000731 (Red Hat Linux
7.3 2.96-
112)] on linux2
Type ``help'', ``copyright'', ``credits'' or ``license'' for more information.
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
'/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
'/usr/local/lib/python2.3/site-packages']
The null string in
<code>sys.path
</code> represents the current working
The expected convention for locally installed packages is to put them
in the
<span class=
"file">.../site-packages/
</span> directory, but you may want to
install Python modules into some arbitrary directory. For example,
your site may have a convention of keeping all software related to the
web server under
<span class=
"file">/www
</span>. Add-on Python modules might then belong
in
<span class=
"file">/www/python
</span>, and in order to import them, this directory
must be added to
<code>sys.path
</code>. There are several different ways to
The most convenient way is to add a path configuration file to a
directory that's already on Python's path, usually to the
<span class=
"file">.../site-packages/
</span> directory. Path configuration files have an
extension of
<span class=
"file">.pth
</span>, and each line must contain a single path
that will be appended to
<code>sys.path
</code>. (Because the new paths are
appended to
<code>sys.path
</code>, modules in the added directories will not
override standard modules. This means you can't use this mechanism
for installing fixed versions of standard modules.)
Paths can be absolute or relative, in which case they're relative to
the directory containing the
<span class=
"file">.pth
</span> file. Any directories added
to the search path will be scanned in turn for
<span class=
"file">.pth
</span> files. See
href=
"http://www.python.org/dev/doc/devel/lib/module-site.html"
title=
"site module documentation"
>site module documentation
</a></em> for more information.
A slightly less convenient way is to edit the
<span class=
"file">site.py
</span> file in
Python's standard library, and modify
<code>sys.path
</code>.
<span class=
"file">site.py
</span>is automatically imported when the Python interpreter is executed,
unless the
<b class=
"programopt">-S
</b> switch is supplied to suppress this
behaviour. So you could simply edit
<span class=
"file">site.py
</span> and add two lines to it:
<div class=
"verbatim"><pre>
sys.path.append('/www/python/')
However, if you reinstall the same major version of Python (perhaps
when upgrading from
2.2 to
2.2.2, for example)
<span class=
"file">site.py
</span> will be
overwritten by the stock version. You'd have to remember that it was
modified and save a copy before doing the installation.
There are two environment variables that can modify
<code>sys.path
</code>.
<a class=
"envvar" id='l2h-
1' xml:id='l2h-
1'
>PYTHONHOME
</a> sets an alternate value for the prefix of the
Python installation. For example, if
<a class=
"envvar" id='l2h-
2' xml:id='l2h-
2'
>PYTHONHOME
</a> is set to
"<tt class="samp
">/www/python</tt>", the search path will be set to
<code>['',
'/www/python/lib/python2.2/', '/www/python/lib/python2.3/plat-linux2',
The
<a class=
"envvar" id='l2h-
3' xml:id='l2h-
3'
>PYTHONPATH
</a> variable can be set to a list of paths that
will be added to the beginning of
<code>sys.path
</code>. For example, if
<a class=
"envvar" id='l2h-
4' xml:id='l2h-
4'
>PYTHONPATH
</a> is set to
"<tt class="samp
">/www/python:/opt/py</tt>", the search
path will begin with
<code>['/www/python', '/opt/py']
</code>. (Note that
directories must exist in order to be added to
<code>sys.path
</code>; the
<tt class=
"module">site
</tt> module removes paths that don't exist.)
Finally,
<code>sys.path
</code> is just a regular Python list, so any Python
application can modify it by adding or removing entries.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"3 Alternate Installation"
href=
"alt-install-windows.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"Installing Python Modules"
href=
"inst.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"5 Distutils Configuration Files"
href=
"config-syntax.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Installing Python Modules
</td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"alt-install-windows.html">3 Alternate Installation
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"inst.html">Installing Python Modules
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"config-syntax.html">5 Distutils Configuration Files
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob