[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / inst / search-path.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<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>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="search-path.html#SECTION000410000000000000000">4.1 Modifying Python's Search Path</a>
</ul>
<!--End of Table of Child-Links-->
</div>
<HR>

<H1><A NAME="SECTION000400000000000000000"></A>
<A NAME="custom-install"></A>
<BR>
4 Custom Installation
</H1>

<P>
Sometimes, the alternate installation schemes described in
section&nbsp;<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>.

<P>
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.)

<P>
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):

<P>
<div class="verbatim"><pre>
python setup.py install --home=~ --install-scripts=scripts
</pre></div>

<P>
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:

<P>
<div class="verbatim"><pre>
python setup.py install --install-scripts=/usr/local/bin
</pre></div>

<P>
(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.)

<P>
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:

<P>
<div class="verbatim"><pre>
python setup.py install --install-purelib=Site --install-platlib=Site
</pre></div>

<P>
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&nbsp;<A HREF="#search-path">4.1</A>
to find out how to modify Python's search path.

<P>
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
installation scheme:

<P>
<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
</pre></div>

<P>
or, equivalently,

<P>
<div class="verbatim"><pre>
python setup.py install --home=~/python \
                        --install-purelib=lib \
                        --install-platlib='lib.$PLAT' \
                        --install-scripts=scripts
                        --install-data=data
</pre></div>

<P>
<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).

<P>
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&nbsp;<A href="config-syntax.html#config-files">5</A>):

<P>
<div class="verbatim"><pre>
[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data
</pre></div>

<P>
or, equivalently,

<P>
<div class="verbatim"><pre>
[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data
</pre></div>

<P>
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,

<P>
<div class="verbatim"><pre>
python setup.py --install-base=/tmp
</pre></div>

<P>
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>.)

<P>
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&nbsp;<A href="config-syntax.html#config-files">5</A> for details.

<P>

<H2><A NAME="SECTION000410000000000000000"></A>
<A NAME="search-path"></A>
<BR>
4.1 Modifying Python's Search Path
</H2>

<P>
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
<code>sys.path</code>.  

<P>
<div class="verbatim"><pre>
$ python
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.
&gt;&gt;&gt; import sys
&gt;&gt;&gt; sys.path
['', '/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']
&gt;&gt;&gt;
</pre></div> 
<P>
The null string in <code>sys.path</code> represents the current working
directory.   

<P>
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
add the directory.

<P>
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.)

<P>
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
<em class="citetitle"><a
 href="http://www.python.org/dev/doc/devel/lib/module-site.html"
 title="site module documentation"
 >site module documentation</a></em> for more information.

<P>
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:

<P>
<div class="verbatim"><pre>
import sys
sys.path.append('/www/python/')
</pre></div>

<P>
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.

<P>
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',
...]</code>.  

<P>
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.)

<P>
Finally, <code>sys.path</code> is just a regular Python list, so any Python
application can modify it by adding or removing entries.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="inst.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="inst.html" title='Installing Python Modules' />
	8	<link rel='last' href='about.html' title='About this document...' />
	9	<link rel='help' href='about.html' title='About this document...' />
	10	<link rel="next" href="config-syntax.html" />
	11	<link rel="prev" href="alt-install-windows.html" />
	12	<link rel="parent" href="inst.html" />
	13	<link rel="next" href="config-syntax.html" />
	14	<meta name='aesop' content='information' />
	15	<title>4 Custom Installation</title>
	16	</head>
	17	<body>
	18	<DIV CLASS="navigation">
	19	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	20	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	21	<tr>
	22	<td class='online-navigation'><a rel="prev" title="3 Alternate Installation"
	23	href="alt-install-windows.html"><img src='../icons/previous.png'
	24	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	25	<td class='online-navigation'><a rel="parent" title="Installing Python Modules"
	26	href="inst.html"><img src='../icons/up.png'
	27	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	28	<td class='online-navigation'><a rel="next" title="5 Distutils Configuration Files"
	29	href="config-syntax.html"><img src='../icons/next.png'
	30	border='0' height='32' alt='Next Page' width='32' /></A></td>
	31	<td align="center" width="100%">Installing Python Modules</td>
	32	<td class='online-navigation'><img src='../icons/blank.png'
	33	border='0' height='32' alt='' width='32' /></td>
	34	<td class='online-navigation'><img src='../icons/blank.png'
	35	border='0' height='32' alt='' width='32' /></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	</tr></table>
	39	<div class='online-navigation'>
	40	<b class="navlabel">Previous:</b>
	41	<a class="sectref" rel="prev" href="alt-install-windows.html">3 Alternate Installation</A>
	42	<b class="navlabel">Up:</b>
	43	<a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A>
	44	<b class="navlabel">Next:</b>
	45	<a class="sectref" rel="next" href="config-syntax.html">5 Distutils Configuration Files</A>
	46	</div>
	47	<hr /></div>
	48	</DIV>
	49	<!--End of Navigation Panel-->
	50	<div class='online-navigation'>
	51	<!--Table of Child-Links-->
	52	<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
	53
	54	<UL CLASS="ChildLinks">
	55	<LI><A href="search-path.html#SECTION000410000000000000000">4.1 Modifying Python's Search Path</a>
	56	</ul>
	57	<!--End of Table of Child-Links-->
	58	</div>
	59	<HR>
	60
	61	<H1><A NAME="SECTION000400000000000000000"></A>
	62	<A NAME="custom-install"></A>
	63	<BR>
	64	4 Custom Installation
65	</H1>
66
67	<P>
68	Sometimes, the alternate installation schemes described in
69	section <A href="alt-install-windows.html#alt-install">3</A> just don't do what you want. You might
70	want to tweak just one or two directories while keeping everything under
71	the same base directory, or you might want to completely redefine the
72	installation scheme. In either case, you're creating a <em>custom
73	installation scheme</em>.
74
75	<P>
76	You probably noticed the column of ``override options'' in the tables
77	describing the alternate installation schemes above. Those options are
78	how you define a custom installation scheme. These override options can
79	be relative, absolute, or explicitly defined in terms of one of the
80	installation base directories. (There are two installation base
81	directories, and they are normally the same--they only differ when you
82	use the <span class="Unix">Unix</span> ``prefix scheme'' and supply different
83	<b class="programopt">--prefix</b> and <b class="programopt">--exec-prefix</b> options.)
84
85	<P>
86	For example, say you're installing a module distribution to your home
87	directory under <span class="Unix">Unix</span>--but you want scripts to go in
88	<span class="file">~/scripts</span> rather than <span class="file">~/bin</span>.
89	As you might expect, you can override this directory with the
90	<b class="programopt">--install-scripts</b> option; in this case, it makes most
91	sense to supply a relative path, which will be interpreted relative to
92	the installation base directory (your home directory, in this case):
93
94	<P>
95	<div class="verbatim"><pre>
96	python setup.py install --home=~ --install-scripts=scripts
97	</pre></div>
98
99	<P>
100	Another <span class="Unix">Unix</span> example: suppose your Python installation was built and
101	installed with a prefix of <span class="file">/usr/local/python</span>, so under a standard
102	installation scripts will wind up in <span class="file">/usr/local/python/bin</span>. If
103	you want them in <span class="file">/usr/local/bin</span> instead, you would supply this
104	absolute directory for the <b class="programopt">--install-scripts</b> option:
105
106	<P>
107	<div class="verbatim"><pre>
108	python setup.py install --install-scripts=/usr/local/bin
109	</pre></div>
110
111	<P>
112	(This performs an installation using the ``prefix scheme,'' where the
113	prefix is whatever your Python interpreter was installed with--
114	<span class="file">/usr/local/python</span> in this case.)
115
116	<P>
117	If you maintain Python on Windows, you might want third-party modules to
118	live in a subdirectory of <span class="du-filevar">prefix</span>, rather than right in
119	<span class="du-filevar">prefix</span> itself. This is almost as easy as customizing the
120	script installation directory--you just have to remember that there are
121	two types of modules to worry about, pure modules and non-pure modules
122	(i.e., modules from a non-pure distribution). For example:
123
124	<P>
125	<div class="verbatim"><pre>
126	python setup.py install --install-purelib=Site --install-platlib=Site
127	</pre></div>
128
129	<P>
130	The specified installation directories are relative to
131	<span class="du-filevar">prefix</span>. Of course, you also have to ensure that these
132	directories are in Python's module search path, such as by putting a
133	<span class="file">.pth</span> file in <span class="du-filevar">prefix</span>. See section <A HREF="#search-path">4.1</A>
134	to find out how to modify Python's search path.
135
136	<P>
137	If you want to define an entire installation scheme, you just have to
138	supply all of the installation directory options. The recommended way
139	to do this is to supply relative paths; for example, if you want to
140	maintain all Python module-related files under <span class="file">python</span> in your
141	home directory, and you want a separate directory for each platform that
142	you use your home directory from, you might define the following
143	installation scheme:
144
145	<P>
146	<div class="verbatim"><pre>
147	python setup.py install --home=~ \
148	--install-purelib=python/lib \
149	--install-platlib=python/lib.$PLAT \
150	--install-scripts=python/scripts
151	--install-data=python/data
152	</pre></div>
153
154	<P>
155	or, equivalently,
156
157	<P>
158	<div class="verbatim"><pre>
159	python setup.py install --home=~/python \
160	--install-purelib=lib \
161	--install-platlib='lib.$PLAT' \
162	--install-scripts=scripts
163	--install-data=data
164	</pre></div>
165
166	<P>
167	<code>$PLAT</code> is not (necessarily) an environment variable--it will be
168	expanded by the Distutils as it parses your command line options, just
169	as it does when parsing your configuration file(s).
170
171	<P>
172	Obviously, specifying the entire installation scheme every time you
173	install a new module distribution would be very tedious. Thus, you can
174	put these options into your Distutils config file (see
175	section <A href="config-syntax.html#config-files">5</A>):
176
177	<P>
178	<div class="verbatim"><pre>
179	[install]
180	install-base=$HOME
181	install-purelib=python/lib
182	install-platlib=python/lib.$PLAT
183	install-scripts=python/scripts
184	install-data=python/data
185	</pre></div>
186
187	<P>
188	or, equivalently,
189
190	<P>
191	<div class="verbatim"><pre>
192	[install]
193	install-base=$HOME/python
194	install-purelib=lib
195	install-platlib=lib.$PLAT
196	install-scripts=scripts
197	install-data=data
198	</pre></div>
199
200	<P>
201	Note that these two are <em>not</em> equivalent if you supply a different
202	installation base directory when you run the setup script. For example,
203
204	<P>
205	<div class="verbatim"><pre>
206	python setup.py --install-base=/tmp
207	</pre></div>
208
209	<P>
210	would install pure modules to <span class="du-filevar">/tmp/python/lib</span> in the first
211	case, and to <span class="du-filevar">/tmp/lib</span> in the second case. (For the second
212	case, you probably want to supply an installation base of
213	<span class="file">/tmp/python</span>.)
214
215	<P>
216	You probably noticed the use of <code>$HOME</code> and <code>$PLAT</code> in the
217	sample configuration file input. These are Distutils configuration
218	variables, which bear a strong resemblance to environment variables.
219	In fact, you can use environment variables in config files on
220	platforms that have such a notion but the Distutils additionally
221	define a few extra variables that may not be in your environment, such
222	as <code>$PLAT</code>. (And of course, on systems that don't have
223	environment variables, such as Mac OS 9, the configuration
224	variables supplied by the Distutils are the only ones you can use.)
225	See section <A href="config-syntax.html#config-files">5</A> for details.
226
227	<P>
228
229	<H2><A NAME="SECTION000410000000000000000"></A>
230	<A NAME="search-path"></A>
231	<BR>
232	4.1 Modifying Python's Search Path
233	</H2>
234
235	<P>
236	When the Python interpreter executes an <tt class="keyword">import</tt> statement, it
237	searches for both Python code and extension modules along a search
238	path. A default value for the path is configured into the Python
239	binary when the interpreter is built. You can determine the path by
240	importing the <tt class="module">sys</tt> module and printing the value of
241	<code>sys.path</code>.
242
243	<P>
244	<div class="verbatim"><pre>
245	$ python
246	Python 2.2 (#11, Oct 3 2002, 13:31:27)
247	[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
248	Type ``help'', ``copyright'', ``credits'' or ``license'' for more information.
249	>>> import sys
250	>>> sys.path
251	['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
252	'/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
253	'/usr/local/lib/python2.3/site-packages']
254	>>>
255	</pre></div>
256	<P>
257	The null string in <code>sys.path</code> represents the current working
258	directory.
259
260	<P>
261	The expected convention for locally installed packages is to put them
262	in the <span class="file">.../site-packages/</span> directory, but you may want to
263	install Python modules into some arbitrary directory. For example,
264	your site may have a convention of keeping all software related to the
265	web server under <span class="file">/www</span>. Add-on Python modules might then belong
266	in <span class="file">/www/python</span>, and in order to import them, this directory
267	must be added to <code>sys.path</code>. There are several different ways to
268	add the directory.
269
270	<P>
271	The most convenient way is to add a path configuration file to a
272	directory that's already on Python's path, usually to the
273	<span class="file">.../site-packages/</span> directory. Path configuration files have an
274	extension of <span class="file">.pth</span>, and each line must contain a single path
275	that will be appended to <code>sys.path</code>. (Because the new paths are
276	appended to <code>sys.path</code>, modules in the added directories will not
277	override standard modules. This means you can't use this mechanism
278	for installing fixed versions of standard modules.)
279
280	<P>
281	Paths can be absolute or relative, in which case they're relative to
282	the directory containing the <span class="file">.pth</span> file. Any directories added
283	to the search path will be scanned in turn for <span class="file">.pth</span> files. See
284	<em class="citetitle"><a
285	href="http://www.python.org/dev/doc/devel/lib/module-site.html"
286	title="site module documentation"
287	>site module documentation</a></em> for more information.
288
289	<P>
290	A slightly less convenient way is to edit the <span class="file">site.py</span> file in
291	Python's standard library, and modify <code>sys.path</code>. <span class="file">site.py</span>
292	is automatically imported when the Python interpreter is executed,
293	unless the <b class="programopt">-S</b> switch is supplied to suppress this
294	behaviour. So you could simply edit <span class="file">site.py</span> and add two lines to it:
295
296	<P>
297	<div class="verbatim"><pre>
298	import sys
299	sys.path.append('/www/python/')
300	</pre></div>
301
302	<P>
303	However, if you reinstall the same major version of Python (perhaps
304	when upgrading from 2.2 to 2.2.2, for example) <span class="file">site.py</span> will be
305	overwritten by the stock version. You'd have to remember that it was
306	modified and save a copy before doing the installation.
307
308	<P>
309	There are two environment variables that can modify <code>sys.path</code>.
310	<a class="envvar" id='l2h-1' xml:id='l2h-1'>PYTHONHOME</a> sets an alternate value for the prefix of the
311	Python installation. For example, if <a class="envvar" id='l2h-2' xml:id='l2h-2'>PYTHONHOME</a> is set to
312	"<tt class="samp">/www/python</tt>", the search path will be set to <code>['',
313	'/www/python/lib/python2.2/', '/www/python/lib/python2.3/plat-linux2',
314	...]</code>.
315
316	<P>
317	The <a class="envvar" id='l2h-3' xml:id='l2h-3'>PYTHONPATH</a> variable can be set to a list of paths that
318	will be added to the beginning of <code>sys.path</code>. For example, if
319	<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
320	path will begin with <code>['/www/python', '/opt/py']</code>. (Note that
321	directories must exist in order to be added to <code>sys.path</code>; the
322	<tt class="module">site</tt> module removes paths that don't exist.)
323
324	<P>
325	Finally, <code>sys.path</code> is just a regular Python list, so any Python
326	application can modify it by adding or removing entries.
327
328	<P>
329
330	<DIV CLASS="navigation">
331	<div class='online-navigation'>
332	<p></p><hr />
333	<table align="center" width="100%" cellpadding="0" cellspacing="2">
334	<tr>
335	<td class='online-navigation'><a rel="prev" title="3 Alternate Installation"
336	href="alt-install-windows.html"><img src='../icons/previous.png'
337	border='0' height='32' alt='Previous Page' width='32' /></A></td>
338	<td class='online-navigation'><a rel="parent" title="Installing Python Modules"
339	href="inst.html"><img src='../icons/up.png'
340	border='0' height='32' alt='Up One Level' width='32' /></A></td>
341	<td class='online-navigation'><a rel="next" title="5 Distutils Configuration Files"
342	href="config-syntax.html"><img src='../icons/next.png'
343	border='0' height='32' alt='Next Page' width='32' /></A></td>
344	<td align="center" width="100%">Installing Python Modules</td>
345	<td class='online-navigation'><img src='../icons/blank.png'
346	border='0' height='32' alt='' width='32' /></td>
347	<td class='online-navigation'><img src='../icons/blank.png'
348	border='0' height='32' alt='' width='32' /></td>
349	<td class='online-navigation'><img src='../icons/blank.png'
350	border='0' height='32' alt='' width='32' /></td>
351	</tr></table>
352	<div class='online-navigation'>
353	<b class="navlabel">Previous:</b>
354	<a class="sectref" rel="prev" href="alt-install-windows.html">3 Alternate Installation</A>
355	<b class="navlabel">Up:</b>
356	<a class="sectref" rel="parent" href="inst.html">Installing Python Modules</A>
357	<b class="navlabel">Next:</b>
358	<a class="sectref" rel="next" href="config-syntax.html">5 Distutils Configuration Files</A>
359	</div>
360	</div>
361	<hr />
362	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
363	</DIV>
364	<!--End of Navigation Panel-->
365	<ADDRESS>
366	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
367	</ADDRESS>
368	</BODY>
369	</HTML>