1.. highlightlang:: none 2 3.. _install-index: 4 5******************************************** 6 Installing Python Modules (Legacy version) 7******************************************** 8 9:Author: Greg Ward 10 11.. TODO: Fill in XXX comments 12 13.. seealso:: 14 15 :ref:`installing-index` 16 The up to date module installation documentations 17 18.. The audience for this document includes people who don't know anything 19 about Python and aren't about to learn the language just in order to 20 install and maintain it for their users, i.e. system administrators. 21 Thus, I have to be sure to explain the basics at some point: 22 sys.path and PYTHONPATH at least. Should probably give pointers to 23 other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. 24 25 Finally, it might be useful to include all the material from my "Care 26 and Feeding of a Python Installation" talk in here somewhere. Yow! 27 28This document describes the Python Distribution Utilities ("Distutils") from the 29end-user's point-of-view, describing how to extend the capabilities of a 30standard Python installation by building and installing third-party Python 31modules and extensions. 32 33 34.. note:: 35 36 This guide only covers the basic tools for building and distributing 37 extensions that are provided as part of this version of Python. Third party 38 tools offer easier to use and more secure alternatives. Refer to the `quick 39 recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__ 40 in the Python Packaging User Guide for more information. 41 42 43.. _inst-intro: 44 45 46Introduction 47============ 48 49Although Python's extensive standard library covers many programming needs, 50there often comes a time when you need to add some new functionality to your 51Python installation in the form of third-party modules. This might be necessary 52to support your own programming, or to support an application that you want to 53use and that happens to be written in Python. 54 55In the past, there has been little support for adding third-party modules to an 56existing Python installation. With the introduction of the Python Distribution 57Utilities (Distutils for short) in Python 2.0, this changed. 58 59This document is aimed primarily at the people who need to install third-party 60Python modules: end-users and system administrators who just need to get some 61Python application running, and existing Python programmers who want to add some 62new goodies to their toolbox. You don't need to know Python to read this 63document; there will be some brief forays into using Python's interactive mode 64to explore your installation, but that's it. If you're looking for information 65on how to distribute your own Python modules so that others may use them, see 66the :ref:`distutils-index` manual. :ref:`debug-setup-script` may also be of 67interest. 68 69 70.. _inst-trivial-install: 71 72Best case: trivial installation 73------------------------------- 74 75In the best case, someone will have prepared a special version of the module 76distribution you want to install that is targeted specifically at your platform 77and is installed just like any other software on your platform. For example, 78the module developer might make an executable installer available for Windows 79users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE, 80Mandrake, and many others), a Debian package for users of Debian-based Linux 81systems, and so forth. 82 83In that case, you would download the installer appropriate to your platform and 84do the obvious thing with it: run it if it's an executable installer, ``rpm 85--install`` it if it's an RPM, etc. You don't need to run Python or a setup 86script, you don't need to compile anything---you might not even need to read any 87instructions (although it's always a good idea to do so anyway). 88 89Of course, things will not always be that easy. You might be interested in a 90module distribution that doesn't have an easy-to-use installer for your 91platform. In that case, you'll have to start with the source distribution 92released by the module's author/maintainer. Installing from a source 93distribution is not too hard, as long as the modules are packaged in the 94standard way. The bulk of this document is about building and installing 95modules from standard source distributions. 96 97 98.. _inst-new-standard: 99 100The new standard: Distutils 101--------------------------- 102 103If you download a module source distribution, you can tell pretty quickly if it 104was packaged and distributed in the standard way, i.e. using the Distutils. 105First, the distribution's name and version number will be featured prominently 106in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or 107:file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly-named 108directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the 109distribution will contain a setup script :file:`setup.py`, and a file named 110:file:`README.txt` or possibly just :file:`README`, which should explain that 111building and installing the module distribution is a simple matter of running 112one command from a terminal:: 113 114 python setup.py install 115 116For Windows, this command should be run from a command prompt window 117(:menuselection:`Start --> Accessories`):: 118 119 setup.py install 120 121If all these things are true, then you already know how to build and install the 122modules you've just downloaded: Run the command above. Unless you need to 123install things in a non-standard way or customize the build process, you don't 124really need this manual. Or rather, the above command is everything you need to 125get out of this manual. 126 127 128.. _inst-standard-install: 129 130Standard Build and Install 131========================== 132 133As described in section :ref:`inst-new-standard`, building and installing a module 134distribution using the Distutils is usually one simple command to run from a 135terminal:: 136 137 python setup.py install 138 139 140.. _inst-platform-variations: 141 142Platform variations 143------------------- 144 145You should always run the setup command from the distribution root directory, 146i.e. the top-level subdirectory that the module source distribution unpacks 147into. For example, if you've just downloaded a module source distribution 148:file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is:: 149 150 gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 151 cd foo-1.0 152 python setup.py install 153 154On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the 155archive file to :file:`C:\\Temp`, then it would unpack into 156:file:`C:\\Temp\\foo-1.0`; you can use either an archive manipulator with a 157graphical user interface (such as WinZip) or a command-line tool (such as 158:program:`unzip` or :program:`pkunzip`) to unpack the archive. Then, open a 159command prompt window and run:: 160 161 cd c:\Temp\foo-1.0 162 python setup.py install 163 164 165.. _inst-splitting-up: 166 167Splitting the job up 168-------------------- 169 170Running ``setup.py install`` builds and installs all modules in one run. If you 171prefer to work incrementally---especially useful if you want to customize the 172build process, or if things are going wrong---you can use the setup script to do 173one thing at a time. This is particularly helpful when the build and install 174will be done by different users---for example, you might want to build a module 175distribution and hand it off to a system administrator for installation (or do 176it yourself, with super-user privileges). 177 178For example, you can build everything in one step, and then install everything 179in a second step, by invoking the setup script twice:: 180 181 python setup.py build 182 python setup.py install 183 184If you do this, you will notice that running the :command:`install` command 185first runs the :command:`build` command, which---in this case---quickly notices 186that it has nothing to do, since everything in the :file:`build` directory is 187up-to-date. 188 189You may not need this ability to break things down often if all you do is 190install modules downloaded off the 'net, but it's very handy for more advanced 191tasks. If you get into distributing your own Python modules and extensions, 192you'll run lots of individual Distutils commands on their own. 193 194 195.. _inst-how-build-works: 196 197How building works 198------------------ 199 200As implied above, the :command:`build` command is responsible for putting the 201files to install into a *build directory*. By default, this is :file:`build` 202under the distribution root; if you're excessively concerned with speed, or want 203to keep the source tree pristine, you can change the build directory with the 204:option:`!--build-base` option. For example:: 205 206 python setup.py build --build-base=/path/to/pybuild/foo-1.0 207 208(Or you could do this permanently with a directive in your system or personal 209Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this 210isn't necessary. 211 212The default layout for the build tree is as follows:: 213 214 --- build/ --- lib/ 215 or 216 --- build/ --- lib.<plat>/ 217 temp.<plat>/ 218 219where ``<plat>`` expands to a brief description of the current OS/hardware 220platform and Python version. The first form, with just a :file:`lib` directory, 221is used for "pure module distributions"---that is, module distributions that 222include only pure Python modules. If a module distribution contains any 223extensions (modules written in C/C++), then the second form, with two ``<plat>`` 224directories, is used. In that case, the :file:`temp.{plat}` directory holds 225temporary files generated by the compile/link process that don't actually get 226installed. In either case, the :file:`lib` (or :file:`lib.{plat}`) directory 227contains all Python modules (pure Python and extensions) that will be installed. 228 229In the future, more directories will be added to handle Python scripts, 230documentation, binary executables, and whatever else is needed to handle the job 231of installing Python modules and applications. 232 233 234.. _inst-how-install-works: 235 236How installation works 237---------------------- 238 239After the :command:`build` command runs (whether you run it explicitly, or the 240:command:`install` command does it for you), the work of the :command:`install` 241command is relatively simple: all it has to do is copy everything under 242:file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation 243directory. 244 245If you don't choose an installation directory---i.e., if you just run ``setup.py 246install``\ ---then the :command:`install` command installs to the standard 247location for third-party Python modules. This location varies by platform and 248by how you built/installed Python itself. On Unix (and Mac OS X, which is also 249Unix-based), it also depends on whether the module distribution being installed 250is pure Python or contains extensions ("non-pure"): 251 252.. tabularcolumns:: |l|l|l|l| 253 254+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ 255| Platform | Standard installation location | Default value | Notes | 256+=================+=====================================================+==================================================+=======+ 257| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | 258+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ 259| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | 260+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ 261| Windows | :file:`{prefix}\\Lib\\site-packages` | :file:`C:\\Python{XY}\\Lib\\site-packages` | \(2) | 262+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ 263 264Notes: 265 266(1) 267 Most Linux distributions include Python as a standard part of the system, so 268 :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on 269 Linux. If you build Python yourself on Linux (or any Unix-like system), the 270 default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`. 271 272(2) 273 The default installation directory on Windows was :file:`C:\\Program 274 Files\\Python` under Python 1.6a1, 1.5.2, and earlier. 275 276:file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python 277is installed to, and where it finds its libraries at run-time. They are always 278the same under Windows, and very often the same under Unix and Mac OS X. You 279can find out what your Python installation uses for :file:`{prefix}` and 280:file:`{exec-prefix}` by running Python in interactive mode and typing a few 281simple commands. Under Unix, just type ``python`` at the shell prompt. Under 282Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> 283Python (command line)`. Once the interpreter is started, you type Python code 284at the prompt. For example, on my Linux system, I type the three Python 285statements shown below, and get the output as shown, to find out my 286:file:`{prefix}` and :file:`{exec-prefix}`: 287 288.. code-block:: pycon 289 290 Python 2.4 (#26, Aug 7 2004, 17:19:02) 291 Type "help", "copyright", "credits" or "license" for more information. 292 >>> import sys 293 >>> sys.prefix 294 '/usr' 295 >>> sys.exec_prefix 296 '/usr' 297 298A few other placeholders are used in this document: :file:`{X.Y}` stands for the 299version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by 300the value of :data:`sys.abiflags` or the empty string for platforms which don't 301define ABI flags; :file:`{distname}` will be replaced by the name of the module 302distribution being installed. Dots and capitalization are important in the 303paths; for example, a value that uses ``python3.2`` on UNIX will typically use 304``Python32`` on Windows. 305 306If you don't want to install modules to the standard location, or if you don't 307have permission to write there, then you need to read about alternate 308installations in section :ref:`inst-alt-install`. If you want to customize your 309installation directories more heavily, see section :ref:`inst-custom-install` on 310custom installations. 311 312 313.. _inst-alt-install: 314 315Alternate Installation 316====================== 317 318Often, it is necessary or desirable to install modules to a location other than 319the standard location for third-party Python modules. For example, on a Unix 320system you might not have permission to write to the standard third-party module 321directory. Or you might wish to try out a module before making it a standard 322part of your local Python installation. This is especially true when upgrading 323a distribution already present: you want to make sure your existing base of 324scripts still works with the new version before actually upgrading. 325 326The Distutils :command:`install` command is designed to make installing module 327distributions to an alternate location simple and painless. The basic idea is 328that you supply a base directory for the installation, and the 329:command:`install` command picks a set of directories (called an *installation 330scheme*) under this base directory in which to install files. The details 331differ across platforms, so read whichever of the following sections applies to 332you. 333 334Note that the various alternate installation schemes are mutually exclusive: you 335can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or 336``--install-base`` and ``--install-platbase``, but you can't mix from these 337groups. 338 339 340.. _inst-alt-install-user: 341 342Alternate installation: the user scheme 343--------------------------------------- 344 345This scheme is designed to be the most convenient solution for users that don't 346have write permission to the global site-packages directory or don't want to 347install into it. It is enabled with a simple option:: 348 349 python setup.py install --user 350 351Files will be installed into subdirectories of :data:`site.USER_BASE` (written 352as :file:`{userbase}` hereafter). This scheme installs pure Python modules and 353extension modules in the same location (also known as :data:`site.USER_SITE`). 354Here are the values for UNIX, including Mac OS X: 355 356=============== =========================================================== 357Type of file Installation directory 358=============== =========================================================== 359modules :file:`{userbase}/lib/python{X.Y}/site-packages` 360scripts :file:`{userbase}/bin` 361data :file:`{userbase}` 362C headers :file:`{userbase}/include/python{X.Y}{abiflags}/{distname}` 363=============== =========================================================== 364 365And here are the values used on Windows: 366 367=============== =========================================================== 368Type of file Installation directory 369=============== =========================================================== 370modules :file:`{userbase}\\Python{XY}\\site-packages` 371scripts :file:`{userbase}\\Python{XY}\\Scripts` 372data :file:`{userbase}` 373C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}` 374=============== =========================================================== 375 376The advantage of using this scheme compared to the other ones described below is 377that the user site-packages directory is under normal conditions always included 378in :data:`sys.path` (see :mod:`site` for more information), which means that 379there is no additional step to perform after running the :file:`setup.py` script 380to finalize the installation. 381 382The :command:`build_ext` command also has a ``--user`` option to add 383:file:`{userbase}/include` to the compiler search path for header files and 384:file:`{userbase}/lib` to the compiler search path for libraries as well as to 385the runtime search path for shared C libraries (rpath). 386 387 388.. _inst-alt-install-home: 389 390Alternate installation: the home scheme 391--------------------------------------- 392 393The idea behind the "home scheme" is that you build and maintain a personal 394stash of Python modules. This scheme's name is derived from the idea of a 395"home" directory on Unix, since it's not unusual for a Unix user to make their 396home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`. 397This scheme can be used by anyone, regardless of the operating system they 398are installing for. 399 400Installing a new module distribution is as simple as :: 401 402 python setup.py install --home=<dir> 403 404where you can supply any directory you like for the :option:`!--home` option. On 405Unix, lazy typists can just type a tilde (``~``); the :command:`install` command 406will expand this to your home directory:: 407 408 python setup.py install --home=~ 409 410To make Python find the distributions installed with this scheme, you may have 411to :ref:`modify Python's search path <inst-search-path>` or edit 412:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit 413:data:`sys.path`. 414 415The :option:`!--home` option defines the installation base directory. Files are 416installed to the following directories under the installation base as follows: 417 418=============== =========================================================== 419Type of file Installation directory 420=============== =========================================================== 421modules :file:`{home}/lib/python` 422scripts :file:`{home}/bin` 423data :file:`{home}` 424C headers :file:`{home}/include/python/{distname}` 425=============== =========================================================== 426 427(Mentally replace slashes with backslashes if you're on Windows.) 428 429 430.. _inst-alt-install-prefix-unix: 431 432Alternate installation: Unix (the prefix scheme) 433------------------------------------------------ 434 435The "prefix scheme" is useful when you wish to use one Python installation to 436perform the build/install (i.e., to run the setup script), but install modules 437into the third-party module directory of a different Python installation (or 438something that looks like a different Python installation). If this sounds a 439trifle unusual, it is---that's why the user and home schemes come before. However, 440there are at least two known cases where the prefix scheme will be useful. 441 442First, consider that many Linux distributions put Python in :file:`/usr`, rather 443than the more traditional :file:`/usr/local`. This is entirely appropriate, 444since in those cases Python is part of "the system" rather than a local add-on. 445However, if you are installing Python modules from source, you probably want 446them to go in :file:`/usr/local/lib/python2.{X}` rather than 447:file:`/usr/lib/python2.{X}`. This can be done with :: 448 449 /usr/bin/python setup.py install --prefix=/usr/local 450 451Another possibility is a network filesystem where the name used to write to a 452remote directory is different from the name used to read it: for example, the 453Python interpreter accessed as :file:`/usr/local/bin/python` might search for 454modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to 455be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`. This could 456be done with :: 457 458 /usr/local/bin/python setup.py install --prefix=/mnt/@server/export 459 460In either case, the :option:`!--prefix` option defines the installation base, and 461the :option:`!--exec-prefix` option defines the platform-specific installation 462base, which is used for platform-specific files. (Currently, this just means 463non-pure module distributions, but could be expanded to C libraries, binary 464executables, etc.) If :option:`!--exec-prefix` is not supplied, it defaults to 465:option:`!--prefix`. Files are installed as follows: 466 467================= ========================================================== 468Type of file Installation directory 469================= ========================================================== 470Python modules :file:`{prefix}/lib/python{X.Y}/site-packages` 471extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages` 472scripts :file:`{prefix}/bin` 473data :file:`{prefix}` 474C headers :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}` 475================= ========================================================== 476 477There is no requirement that :option:`!--prefix` or :option:`!--exec-prefix` 478actually point to an alternate Python installation; if the directories listed 479above do not already exist, they are created at installation time. 480 481Incidentally, the real reason the prefix scheme is important is simply that a 482standard Unix installation uses the prefix scheme, but with :option:`!--prefix` 483and :option:`!--exec-prefix` supplied by Python itself as ``sys.prefix`` and 484``sys.exec_prefix``. Thus, you might think you'll never use the prefix scheme, 485but every time you run ``python setup.py install`` without any other options, 486you're using it. 487 488Note that installing extensions to an alternate Python installation has no 489effect on how those extensions are built: in particular, the Python header files 490(:file:`Python.h` and friends) installed with the Python interpreter used to run 491the setup script will be used in compiling extensions. It is your 492responsibility to ensure that the interpreter used to run extensions installed 493in this way is compatible with the interpreter used to build them. The best way 494to do this is to ensure that the two interpreters are the same version of Python 495(possibly different builds, or possibly copies of the same build). (Of course, 496if your :option:`!--prefix` and :option:`!--exec-prefix` don't even point to an 497alternate Python installation, this is immaterial.) 498 499 500.. _inst-alt-install-prefix-windows: 501 502Alternate installation: Windows (the prefix scheme) 503--------------------------------------------------- 504 505Windows has no concept of a user's home directory, and since the standard Python 506installation under Windows is simpler than under Unix, the :option:`!--prefix` 507option has traditionally been used to install additional packages in separate 508locations on Windows. :: 509 510 python setup.py install --prefix="\Temp\Python" 511 512to install modules to the :file:`\\Temp\\Python` directory on the current drive. 513 514The installation base is defined by the :option:`!--prefix` option; the 515:option:`!--exec-prefix` option is not supported under Windows, which means that 516pure Python modules and extension modules are installed into the same location. 517Files are installed as follows: 518 519=============== ========================================================== 520Type of file Installation directory 521=============== ========================================================== 522modules :file:`{prefix}\\Lib\\site-packages` 523scripts :file:`{prefix}\\Scripts` 524data :file:`{prefix}` 525C headers :file:`{prefix}\\Include\\{distname}` 526=============== ========================================================== 527 528 529.. _inst-custom-install: 530 531Custom Installation 532=================== 533 534Sometimes, the alternate installation schemes described in section 535:ref:`inst-alt-install` just don't do what you want. You might want to tweak just 536one or two directories while keeping everything under the same base directory, 537or you might want to completely redefine the installation scheme. In either 538case, you're creating a *custom installation scheme*. 539 540To create a custom installation scheme, you start with one of the alternate 541schemes and override some of the installation directories used for the various 542types of files, using these options: 543 544====================== ======================= 545Type of file Override option 546====================== ======================= 547Python modules ``--install-purelib`` 548extension modules ``--install-platlib`` 549all modules ``--install-lib`` 550scripts ``--install-scripts`` 551data ``--install-data`` 552C headers ``--install-headers`` 553====================== ======================= 554 555These override options can be relative, absolute, 556or explicitly defined in terms of one of the installation base directories. 557(There are two installation base directories, and they are normally the 558same---they only differ when you use the Unix "prefix scheme" and supply 559different ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` 560will override values computed or given for ``--install-purelib`` and 561``--install-platlib``, and is recommended for schemes that don't make a 562difference between Python and extension modules.) 563 564For example, say you're installing a module distribution to your home directory 565under Unix---but you want scripts to go in :file:`~/scripts` rather than 566:file:`~/bin`. As you might expect, you can override this directory with the 567:option:`!--install-scripts` option; in this case, it makes most sense to supply 568a relative path, which will be interpreted relative to the installation base 569directory (your home directory, in this case):: 570 571 python setup.py install --home=~ --install-scripts=scripts 572 573Another Unix example: suppose your Python installation was built and installed 574with a prefix of :file:`/usr/local/python`, so under a standard installation 575scripts will wind up in :file:`/usr/local/python/bin`. If you want them in 576:file:`/usr/local/bin` instead, you would supply this absolute directory for the 577:option:`!--install-scripts` option:: 578 579 python setup.py install --install-scripts=/usr/local/bin 580 581(This performs an installation using the "prefix scheme," where the prefix is 582whatever your Python interpreter was installed with--- :file:`/usr/local/python` 583in this case.) 584 585If you maintain Python on Windows, you might want third-party modules to live in 586a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` 587itself. This is almost as easy as customizing the script installation 588directory---you just have to remember that there are two types of modules 589to worry about, Python and extension modules, which can conveniently be both 590controlled by one option:: 591 592 python setup.py install --install-lib=Site 593 594The specified installation directory is relative to :file:`{prefix}`. Of 595course, you also have to ensure that this directory is in Python's module 596search path, such as by putting a :file:`.pth` file in a site directory (see 597:mod:`site`). See section :ref:`inst-search-path` to find out how to modify 598Python's search path. 599 600If you want to define an entire installation scheme, you just have to supply all 601of the installation directory options. The recommended way to do this is to 602supply relative paths; for example, if you want to maintain all Python 603module-related files under :file:`python` in your home directory, and you want a 604separate directory for each platform that you use your home directory from, you 605might define the following installation scheme:: 606 607 python setup.py install --home=~ \ 608 --install-purelib=python/lib \ 609 --install-platlib=python/lib.$PLAT \ 610 --install-scripts=python/scripts 611 --install-data=python/data 612 613or, equivalently, :: 614 615 python setup.py install --home=~/python \ 616 --install-purelib=lib \ 617 --install-platlib='lib.$PLAT' \ 618 --install-scripts=scripts 619 --install-data=data 620 621``$PLAT`` is not (necessarily) an environment variable---it will be expanded by 622the Distutils as it parses your command line options, just as it does when 623parsing your configuration file(s). 624 625Obviously, specifying the entire installation scheme every time you install a 626new module distribution would be very tedious. Thus, you can put these options 627into your Distutils config file (see section :ref:`inst-config-files`): 628 629.. code-block:: ini 630 631 [install] 632 install-base=$HOME 633 install-purelib=python/lib 634 install-platlib=python/lib.$PLAT 635 install-scripts=python/scripts 636 install-data=python/data 637 638or, equivalently, 639 640.. code-block:: ini 641 642 [install] 643 install-base=$HOME/python 644 install-purelib=lib 645 install-platlib=lib.$PLAT 646 install-scripts=scripts 647 install-data=data 648 649Note that these two are *not* equivalent if you supply a different installation 650base directory when you run the setup script. For example, :: 651 652 python setup.py install --install-base=/tmp 653 654would install pure modules to :file:`/tmp/python/lib` in the first case, and 655to :file:`/tmp/lib` in the second case. (For the second case, you probably 656want to supply an installation base of :file:`/tmp/python`.) 657 658You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample 659configuration file input. These are Distutils configuration variables, which 660bear a strong resemblance to environment variables. In fact, you can use 661environment variables in config files on platforms that have such a notion but 662the Distutils additionally define a few extra variables that may not be in your 663environment, such as ``$PLAT``. (And of course, on systems that don't have 664environment variables, such as Mac OS 9, the configuration variables supplied by 665the Distutils are the only ones you can use.) See section :ref:`inst-config-files` 666for details. 667 668.. note:: When a :ref:`virtual environment <venv-def>` is activated, any options 669 that change the installation path will be ignored from all distutils configuration 670 files to prevent inadvertently installing projects outside of the virtual 671 environment. 672 673.. XXX need some Windows examples---when would custom installation schemes be 674 needed on those platforms? 675 676 677.. XXX Move this to Doc/using 678 679.. _inst-search-path: 680 681Modifying Python's Search Path 682------------------------------ 683 684When the Python interpreter executes an :keyword:`import` statement, it searches 685for both Python code and extension modules along a search path. A default value 686for the path is configured into the Python binary when the interpreter is built. 687You can determine the path by importing the :mod:`sys` module and printing the 688value of ``sys.path``. :: 689 690 $ python 691 Python 2.2 (#11, Oct 3 2002, 13:31:27) 692 [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2 693 Type "help", "copyright", "credits" or "license" for more information. 694 >>> import sys 695 >>> sys.path 696 ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', 697 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', 698 '/usr/local/lib/python2.3/site-packages'] 699 >>> 700 701The null string in ``sys.path`` represents the current working directory. 702 703The expected convention for locally installed packages is to put them in the 704:file:`{...}/site-packages/` directory, but you may want to install Python 705modules into some arbitrary directory. For example, your site may have a 706convention of keeping all software related to the web server under :file:`/www`. 707Add-on Python modules might then belong in :file:`/www/python`, and in order to 708import them, this directory must be added to ``sys.path``. There are several 709different ways to add the directory. 710 711The most convenient way is to add a path configuration file to a directory 712that's already on Python's path, usually to the :file:`.../site-packages/` 713directory. Path configuration files have an extension of :file:`.pth`, and each 714line must contain a single path that will be appended to ``sys.path``. (Because 715the new paths are appended to ``sys.path``, modules in the added directories 716will not override standard modules. This means you can't use this mechanism for 717installing fixed versions of standard modules.) 718 719Paths can be absolute or relative, in which case they're relative to the 720directory containing the :file:`.pth` file. See the documentation of 721the :mod:`site` module for more information. 722 723A slightly less convenient way is to edit the :file:`site.py` file in Python's 724standard library, and modify ``sys.path``. :file:`site.py` is automatically 725imported when the Python interpreter is executed, unless the :option:`-S` switch 726is supplied to suppress this behaviour. So you could simply edit 727:file:`site.py` and add two lines to it: 728 729.. code-block:: python 730 731 import sys 732 sys.path.append('/www/python/') 733 734However, if you reinstall the same major version of Python (perhaps when 735upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by 736the stock version. You'd have to remember that it was modified and save a copy 737before doing the installation. 738 739There are two environment variables that can modify ``sys.path``. 740:envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python 741installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``, 742the search path will be set to ``['', '/www/python/lib/pythonX.Y/', 743'/www/python/lib/pythonX.Y/plat-linux2', ...]``. 744 745The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be 746added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is 747set to ``/www/python:/opt/py``, the search path will begin with 748``['/www/python', '/opt/py']``. (Note that directories must exist in order to 749be added to ``sys.path``; the :mod:`site` module removes paths that don't 750exist.) 751 752Finally, ``sys.path`` is just a regular Python list, so any Python application 753can modify it by adding or removing entries. 754 755 756.. _inst-config-files: 757 758Distutils Configuration Files 759============================= 760 761As mentioned above, you can use Distutils configuration files to record personal 762or site preferences for any Distutils options. That is, any option to any 763command can be stored in one of two or three (depending on your platform) 764configuration files, which will be consulted before the command-line is parsed. 765This means that configuration files will override default values, and the 766command-line will in turn override configuration files. Furthermore, if 767multiple configuration files apply, values from "earlier" files are overridden 768by "later" files. 769 770 771.. _inst-config-filenames: 772 773Location and names of config files 774---------------------------------- 775 776The names and locations of the configuration files vary slightly across 777platforms. On Unix and Mac OS X, the three configuration files (in the order 778they are processed) are: 779 780+--------------+----------------------------------------------------------+-------+ 781| Type of file | Location and filename | Notes | 782+==============+==========================================================+=======+ 783| system | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) | 784+--------------+----------------------------------------------------------+-------+ 785| personal | :file:`$HOME/.pydistutils.cfg` | \(2) | 786+--------------+----------------------------------------------------------+-------+ 787| local | :file:`setup.cfg` | \(3) | 788+--------------+----------------------------------------------------------+-------+ 789 790And on Windows, the configuration files are: 791 792+--------------+-------------------------------------------------+-------+ 793| Type of file | Location and filename | Notes | 794+==============+=================================================+=======+ 795| system | :file:`{prefix}\\Lib\\distutils\\distutils.cfg` | \(4) | 796+--------------+-------------------------------------------------+-------+ 797| personal | :file:`%HOME%\\pydistutils.cfg` | \(5) | 798+--------------+-------------------------------------------------+-------+ 799| local | :file:`setup.cfg` | \(3) | 800+--------------+-------------------------------------------------+-------+ 801 802On all platforms, the "personal" file can be temporarily disabled by 803passing the `--no-user-cfg` option. 804 805Notes: 806 807(1) 808 Strictly speaking, the system-wide configuration file lives in the directory 809 where the Distutils are installed; under Python 1.6 and later on Unix, this is 810 as shown. For Python 1.5.2, the Distutils will normally be installed to 811 :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system 812 configuration file should be put there under Python 1.5.2. 813 814(2) 815 On Unix, if the :envvar:`HOME` environment variable is not defined, the user's 816 home directory will be determined with the :func:`getpwuid` function from the 817 standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser` 818 function used by Distutils. 819 820(3) 821 I.e., in the current directory (usually the location of the setup script). 822 823(4) 824 (See also note (1).) Under Python 1.6 and later, Python's default "installation 825 prefix" is :file:`C:\\Python`, so the system configuration file is normally 826 :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the 827 default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not 828 part of the standard library---so the system configuration file would be 829 :file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python 830 1.5.2 installation under Windows. 831 832(5) 833 On Windows, if the :envvar:`HOME` environment variable is not defined, 834 :envvar:`USERPROFILE` then :envvar:`HOMEDRIVE` and :envvar:`HOMEPATH` will 835 be tried. This is done by the :func:`os.path.expanduser` function used 836 by Distutils. 837 838 839.. _inst-config-syntax: 840 841Syntax of config files 842---------------------- 843 844The Distutils configuration files all have the same syntax. The config files 845are grouped into sections. There is one section for each Distutils command, 846plus a ``global`` section for global options that affect every command. Each 847section consists of one option per line, specified as ``option=value``. 848 849For example, the following is a complete config file that just forces all 850commands to run quietly by default: 851 852.. code-block:: ini 853 854 [global] 855 verbose=0 856 857If this is installed as the system config file, it will affect all processing of 858any Python module distribution by any user on the current system. If it is 859installed as your personal config file (on systems that support them), it will 860affect only module distributions processed by you. And if it is used as the 861:file:`setup.cfg` for a particular module distribution, it affects only that 862distribution. 863 864You could override the default "build base" directory and make the 865:command:`build\*` commands always forcibly rebuild all files with the 866following: 867 868.. code-block:: ini 869 870 [build] 871 build-base=blib 872 force=1 873 874which corresponds to the command-line arguments :: 875 876 python setup.py build --build-base=blib --force 877 878except that including the :command:`build` command on the command-line means 879that command will be run. Including a particular command in config files has no 880such implication; it only means that if the command is run, the options in the 881config file will apply. (Or if other commands that derive values from it are 882run, they will use the values in the config file.) 883 884You can find out the complete list of options for any command using the 885:option:`!--help` option, e.g.:: 886 887 python setup.py build --help 888 889and you can find out the complete list of global options by using 890:option:`!--help` without a command:: 891 892 python setup.py --help 893 894See also the "Reference" section of the "Distributing Python Modules" manual. 895 896 897.. _inst-building-ext: 898 899Building Extensions: Tips and Tricks 900==================================== 901 902Whenever possible, the Distutils try to use the configuration information made 903available by the Python interpreter used to run the :file:`setup.py` script. 904For example, the same compiler and linker flags used to compile Python will also 905be used for compiling extensions. Usually this will work well, but in 906complicated situations this might be inappropriate. This section discusses how 907to override the usual Distutils behaviour. 908 909 910.. _inst-tweak-flags: 911 912Tweaking compiler/linker flags 913------------------------------ 914 915Compiling a Python extension written in C or C++ will sometimes require 916specifying custom flags for the compiler and linker in order to use a particular 917library or produce a special kind of object code. This is especially true if the 918extension hasn't been tested on your platform, or if you're trying to 919cross-compile Python. 920 921In the most general case, the extension author might have foreseen that 922compiling the extensions would be complicated, and provided a :file:`Setup` file 923for you to edit. This will likely only be done if the module distribution 924contains many separate extension modules, or if they often require elaborate 925sets of compiler flags in order to work. 926 927A :file:`Setup` file, if present, is parsed in order to get a list of extensions 928to build. Each line in a :file:`Setup` describes a single module. Lines have 929the following structure:: 930 931 module ... [sourcefile ...] [cpparg ...] [library ...] 932 933 934Let's examine each of the fields in turn. 935 936* *module* is the name of the extension module to be built, and should be a 937 valid Python identifier. You can't just change this in order to rename a module 938 (edits to the source code would also be needed), so this should be left alone. 939 940* *sourcefile* is anything that's likely to be a source code file, at least 941 judging by the filename. Filenames ending in :file:`.c` are assumed to be 942 written in C, filenames ending in :file:`.C`, :file:`.cc`, and :file:`.c++` are 943 assumed to be C++, and filenames ending in :file:`.m` or :file:`.mm` are assumed 944 to be in Objective C. 945 946* *cpparg* is an argument for the C preprocessor, and is anything starting with 947 :option:`!-I`, :option:`!-D`, :option:`!-U` or :option:`!-C`. 948 949* *library* is anything ending in :file:`.a` or beginning with :option:`!-l` or 950 :option:`!-L`. 951 952If a particular platform requires a special library on your platform, you can 953add it by editing the :file:`Setup` file and running ``python setup.py build``. 954For example, if the module defined by the line :: 955 956 foo foomodule.c 957 958must be linked with the math library :file:`libm.a` on your platform, simply add 959:option:`!-lm` to the line:: 960 961 foo foomodule.c -lm 962 963Arbitrary switches intended for the compiler or the linker can be supplied with 964the :option:`!-Xcompiler` *arg* and :option:`!-Xlinker` *arg* options:: 965 966 foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm 967 968The next option after :option:`!-Xcompiler` and :option:`!-Xlinker` will be 969appended to the proper command line, so in the above example the compiler will 970be passed the :option:`!-o32` option, and the linker will be passed 971:option:`!-shared`. If a compiler option requires an argument, you'll have to 972supply multiple :option:`!-Xcompiler` options; for example, to pass ``-x c++`` 973the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``. 974 975Compiler flags can also be supplied through setting the :envvar:`CFLAGS` 976environment variable. If set, the contents of :envvar:`CFLAGS` will be added to 977the compiler flags specified in the :file:`Setup` file. 978 979 980.. _inst-non-ms-compilers: 981 982Using non-Microsoft compilers on Windows 983---------------------------------------- 984 985.. sectionauthor:: Rene Liebscher <R.Liebscher@gmx.de> 986 987 988 989Borland/CodeGear C++ 990^^^^^^^^^^^^^^^^^^^^ 991 992This subsection describes the necessary steps to use Distutils with the Borland 993C++ compiler version 5.5. First you have to know that Borland's object file 994format (OMF) is different from the format used by the Python version you can 995download from the Python or ActiveState Web site. (Python is built with 996Microsoft Visual C++, which uses COFF as the object file format.) For this 997reason you have to convert Python's library :file:`python25.lib` into the 998Borland format. You can do this as follows: 999 1000.. Should we mention that users have to create cfg-files for the compiler? 1001.. see also http://community.borland.com/article/0,1410,21205,00.html 1002 1003:: 1004 1005 coff2omf python25.lib python25_bcpp.lib 1006 1007The :file:`coff2omf` program comes with the Borland compiler. The file 1008:file:`python25.lib` is in the :file:`Libs` directory of your Python 1009installation. If your extension uses other libraries (zlib, ...) you have to 1010convert them too. 1011 1012The converted files have to reside in the same directories as the normal 1013libraries. 1014 1015How does Distutils manage to use these libraries with their changed names? If 1016the extension needs a library (eg. :file:`foo`) Distutils checks first if it 1017finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then 1018uses this library. In the case it doesn't find such a special library it uses 1019the default name (:file:`foo.lib`.) [#]_ 1020 1021To let Distutils compile your extension with Borland C++ you now have to type:: 1022 1023 python setup.py build --compiler=bcpp 1024 1025If you want to use the Borland C++ compiler as the default, you could specify 1026this in your personal or system-wide configuration file for Distutils (see 1027section :ref:`inst-config-files`.) 1028 1029 1030.. seealso:: 1031 1032 `C++Builder Compiler <https://www.embarcadero.com/products>`_ 1033 Information about the free C++ compiler from Borland, including links to the 1034 download pages. 1035 1036 `Creating Python Extensions Using Borland's Free Compiler <http://www.cyberus.ca/~g_will/pyExtenDL.shtml>`_ 1037 Document describing how to use Borland's free command-line C++ compiler to build 1038 Python. 1039 1040 1041GNU C / Cygwin / MinGW 1042^^^^^^^^^^^^^^^^^^^^^^ 1043 1044This section describes the necessary steps to use Distutils with the GNU C/C++ 1045compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter 1046that was built with Cygwin, everything should work without any of these 1047following steps. 1048 1049Not all extensions can be built with MinGW or Cygwin, but many can. Extensions 1050most likely to not work are those that use C++ or depend on Microsoft Visual C 1051extensions. 1052 1053To let Distutils compile your extension with Cygwin you have to type:: 1054 1055 python setup.py build --compiler=cygwin 1056 1057and for Cygwin in no-cygwin mode [#]_ or for MinGW type:: 1058 1059 python setup.py build --compiler=mingw32 1060 1061If you want to use any of these options/compilers as default, you should 1062consider writing it in your personal or system-wide configuration file for 1063Distutils (see section :ref:`inst-config-files`.) 1064 1065Older Versions of Python and MinGW 1066"""""""""""""""""""""""""""""""""" 1067The following instructions only apply if you're using a version of Python 1068inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with 1069binutils-2.13.90-20030111-1). 1070 1071These compilers require some special libraries. This task is more complex than 1072for Borland's C++, because there is no program to convert the library. First 1073you have to create a list of symbols which the Python DLL exports. (You can find 1074a good program for this task at 1075https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/). 1076 1077.. I don't understand what the next line means. --amk 1078.. (inclusive the references on data structures.) 1079 1080:: 1081 1082 pexports python25.dll >python25.def 1083 1084The location of an installed :file:`python25.dll` will depend on the 1085installation options and the version and language of Windows. In a "just for 1086me" installation, it will appear in the root of the installation directory. In 1087a shared installation, it will be located in the system directory. 1088 1089Then you can create from these information an import library for gcc. :: 1090 1091 /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a 1092 1093The resulting library has to be placed in the same directory as 1094:file:`python25.lib`. (Should be the :file:`libs` directory under your Python 1095installation directory.) 1096 1097If your extension uses other libraries (zlib,...) you might have to convert 1098them too. The converted files have to reside in the same directories as the 1099normal libraries do. 1100 1101 1102.. seealso:: 1103 1104 `Building Python modules on MS Windows platform with MinGW <http://old.zope.org/Members/als/tips/win32_mingw_modules>`_ 1105 Information about building the required libraries for the MinGW environment. 1106 1107 1108.. rubric:: Footnotes 1109 1110.. [#] This also means you could replace all existing COFF-libraries with OMF-libraries 1111 of the same name. 1112 1113.. [#] Check https://www.sourceware.org/cygwin/ and http://www.mingw.org/ for more 1114 information 1115 1116.. [#] Then you have no POSIX emulation available, but you also don't need 1117 :file:`cygwin1.dll`. 1118