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