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