Commit | Line | Data |
---|---|---|
86530b38 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> |