Lines Matching +full:install +full:- +full:module
3 .. _install-index:
18 :ref:`What's New <distutils-deprecated>` entry for more information.
22 :ref:`installing-index`
23 The up to date module installation documentation. For regular Python
33 recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__
37 .. _inst-intro:
54 See :ref:`installing-index` and :ref:`distributing-index` for more details.
59 .. _inst-new-standard:
62 ------------------------------------
64 If you download a module source distribution, you can tell pretty quickly if it
67 in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or
68 :file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly named
69 directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the
72 building and installing the module distribution is a simple matter of running
75 python setup.py install
78 (:menuselection:`Start --> Accessories`)::
80 setup.py install
82 If all these things are true, then you already know how to build and install the
84 install things in a non-standard way or customize the build process, you don't
89 .. _inst-standard-install:
91 Standard Build and Install
94 As described in section :ref:`inst-new-standard`, building and installing a module
98 python setup.py install
101 .. _inst-platform-variations:
104 -------------------
107 i.e. the top-level subdirectory that the module source distribution unpacks
108 into. For example, if you've just downloaded a module source distribution
109 :file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is::
111 gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
112 cd foo-1.0
113 python setup.py install
115 On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the
117 :file:`C:\\Temp\\foo-1.0`; you can use either an archive manipulator with a
118 graphical user interface (such as WinZip) or a command-line tool (such as
122 cd c:\Temp\foo-1.0
123 python setup.py install
126 .. _inst-splitting-up:
129 --------------------
131 Running ``setup.py install`` builds and installs all modules in one run. If you
132 prefer to work incrementally---especially useful if you want to customize the
133 build process, or if things are going wrong---you can use the setup script to do
134 one thing at a time. This is particularly helpful when the build and install
135 will be done by different users---for example, you might want to build a module
137 it yourself, with super-user privileges).
139 For example, you can build everything in one step, and then install everything
143 python setup.py install
145 If you do this, you will notice that running the :command:`install` command
146 first runs the :command:`build` command, which---in this case---quickly notices
148 up-to-date.
151 install modules downloaded off the 'net, but it's very handy for more advanced
156 .. _inst-how-build-works:
159 ------------------
162 files to install into a *build directory*. By default, this is :file:`build`
165 :option:`!--build-base` option. For example::
167 python setup.py build --build-base=/path/to/pybuild/foo-1.0
170 Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this
175 --- build/ --- lib/
177 --- build/ --- lib.<plat>/
182 is used for "pure module distributions"---that is, module distributions that
183 include only pure Python modules. If a module distribution contains any
195 .. _inst-how-install-works:
198 ----------------------
201 :command:`install` command does it for you), the work of the :command:`install`
206 If you don't choose an installation directory---i.e., if you just run ``setup.py
207 install``\ ---then the :command:`install` command installs to the standard
208 location for third-party Python modules. This location varies by platform and
210 Unix-based), it also depends on whether the module distribution being installed
211 is pure Python or contains extensions ("non-pure"):
215 +-----------------+-----------------------------------------------------+--------------------------…
218 …pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y…
219 +-----------------+-----------------------------------------------------+--------------------------…
220 | Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/pyt…
221 +-----------------+-----------------------------------------------------+--------------------------…
222 | Windows | :file:`{prefix}\\Lib\\site-packages` | :file:`C:\\Python{XY}\\Li…
223 +-----------------+-----------------------------------------------------+--------------------------…
229 :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on
230 Linux. If you build Python yourself on Linux (or any Unix-like system), the
231 default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`.
237 :file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python
238 is installed to, and where it finds its libraries at run-time. They are always
241 :file:`{exec-prefix}` by running Python in interactive mode and typing a few
243 Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
247 :file:`{prefix}` and :file:`{exec-prefix}`:
249 .. code-block:: pycon
262 define ABI flags; :file:`{distname}` will be replaced by the name of the module
267 If you don't want to install modules to the standard location, or if you don't
269 installations in section :ref:`inst-alt-install`. If you want to customize your
270 installation directories more heavily, see section :ref:`inst-custom-install` on
274 .. _inst-alt-install:
279 Often, it is necessary or desirable to install modules to a location other than
280 the standard location for third-party Python modules. For example, on a Unix
281 system you might not have permission to write to the standard third-party module
282 directory. Or you might wish to try out a module before making it a standard
287 The Distutils :command:`install` command is designed to make installing module
290 :command:`install` command picks a set of directories (called an *installation
291 scheme*) under this base directory in which to install files. The details
296 can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or
297 ``--install-base`` and ``--install-platbase``, but you can't mix from these
301 .. _inst-alt-install-user:
304 ---------------------------------------
307 have write permission to the global site-packages directory or don't want to
308 install into it. It is enabled with a simple option::
310 python setup.py install --user
320 modules :file:`{userbase}/lib/python{X.Y}/site-packages`
331 modules :file:`{userbase}\\Python{XY}\\site-packages`
338 that the user site-packages directory is under normal conditions always included
343 The :command:`build_ext` command also has a ``--user`` option to add
349 .. _inst-alt-install-home:
352 ---------------------------------------
361 Installing a new module distribution is as simple as ::
363 python setup.py install --home=<dir>
365 where you can supply any directory you like for the :option:`!--home` option. On
366 Unix, lazy typists can just type a tilde (``~``); the :command:`install` command
369 python setup.py install --home=~
372 to :ref:`modify Python's search path <inst-search-path>` or edit
376 The :option:`!--home` option defines the installation base directory. Files are
391 .. _inst-alt-install-prefix-unix:
394 ------------------------------------------------
397 perform the build/install (i.e., to run the setup script), but install modules
398 into the third-party module directory of a different Python installation (or
400 trifle unusual, it is---that's why the user and home schemes come before. However,
405 since in those cases Python is part of "the system" rather than a local add-on.
410 /usr/bin/python setup.py install --prefix=/usr/local
419 /usr/local/bin/python setup.py install --prefix=/mnt/@server/export
421 In either case, the :option:`!--prefix` option defines the installation base, and
422 the :option:`!--exec-prefix` option defines the platform-specific installation
423 base, which is used for platform-specific files. (Currently, this just means
424 non-pure module distributions, but could be expanded to C libraries, binary
425 executables, etc.) If :option:`!--exec-prefix` is not supplied, it defaults to
426 :option:`!--prefix`. Files are installed as follows:
431 Python modules :file:`{prefix}/lib/python{X.Y}/site-packages`
432 extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages`
438 There is no requirement that :option:`!--prefix` or :option:`!--exec-prefix`
443 standard Unix installation uses the prefix scheme, but with :option:`!--prefix`
444 and :option:`!--exec-prefix` supplied by Python itself as ``sys.prefix`` and
446 but every time you run ``python setup.py install`` without any other options,
457 if your :option:`!--prefix` and :option:`!--exec-prefix` don't even point to an
461 .. _inst-alt-install-prefix-windows:
464 ---------------------------------------------------
467 installation under Windows is simpler than under Unix, the :option:`!--prefix`
468 option has traditionally been used to install additional packages in separate
471 python setup.py install --prefix="\Temp\Python"
473 to install modules to the :file:`\\Temp\\Python` directory on the current drive.
475 The installation base is defined by the :option:`!--prefix` option; the
476 :option:`!--exec-prefix` option is not supported under Windows, which means that
483 modules :file:`{prefix}\\Lib\\site-packages`
490 .. _inst-custom-install:
496 :ref:`inst-alt-install` just don't do what you want. You might want to tweak just
508 Python modules ``--install-purelib``
509 extension modules ``--install-platlib``
510 all modules ``--install-lib``
511 scripts ``--install-scripts``
512 data ``--install-data``
513 C headers ``--install-headers``
519 same---they only differ when you use the Unix "prefix scheme" and supply
520 different ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib``
521 will override values computed or given for ``--install-purelib`` and
522 ``--install-platlib``, and is recommended for schemes that don't make a
525 For example, say you're installing a module distribution to your home directory
526 under Unix---but you want scripts to go in :file:`~/scripts` rather than
528 :option:`!--install-scripts` option; in this case, it makes most sense to supply
532 python setup.py install --home=~ --install-scripts=scripts
538 :option:`!--install-scripts` option::
540 python setup.py install --install-scripts=/usr/local/bin
543 whatever your Python interpreter was installed with--- :file:`/usr/local/python`
546 If you maintain Python on Windows, you might want third-party modules to live in
549 directory---you just have to remember that there are two types of modules
553 python setup.py install --install-lib=Site
556 course, you also have to ensure that this directory is in Python's module
558 :mod:`site`). See section :ref:`inst-search-path` to find out how to modify
564 module-related files under :file:`python` in your home directory, and you want a
568 python setup.py install --home=~ \
569 --install-purelib=python/lib \
570 --install-platlib=python/lib.$PLAT \
571 --install-scripts=python/scripts
572 --install-data=python/data
576 python setup.py install --home=~/python \
577 --install-purelib=lib \
578 --install-platlib='lib.$PLAT' \
579 --install-scripts=scripts
580 --install-data=data
582 ``$PLAT`` is not (necessarily) an environment variable---it will be expanded by
586 Obviously, specifying the entire installation scheme every time you install a
587 new module distribution would be very tedious. Thus, you can put these options
588 into your Distutils config file (see section :ref:`inst-config-files`):
590 .. code-block:: ini
592 [install]
593 install-base=$HOME
594 install-purelib=python/lib
595 install-platlib=python/lib.$PLAT
596 install-scripts=python/scripts
597 install-data=python/data
601 .. code-block:: ini
603 [install]
604 install-base=$HOME/python
605 install-purelib=lib
606 install-platlib=lib.$PLAT
607 install-scripts=scripts
608 install-data=data
613 python setup.py install --install-base=/tmp
615 would install pure modules to :file:`/tmp/python/lib` in the first case, and
626 the Distutils are the only ones you can use.) See section :ref:`inst-config-files`
629 .. note:: When a :ref:`virtual environment <venv-def>` is activated, any options
634 .. XXX need some Windows examples---when would custom installation schemes be
640 .. _inst-search-path:
643 ------------------------------
648 You can determine the path by importing the :mod:`sys` module and printing the
653 [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
657 ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
658 '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
659 '/usr/local/lib/python2.3/site-packages']
665 :file:`{...}/site-packages/` directory, but you may want to install Python
668 Add-on Python modules might then belong in :file:`/www/python`, and in order to
673 that's already on Python's path, usually to the :file:`.../site-packages/`
682 the :mod:`site` module for more information.
686 imported when the Python interpreter is executed, unless the :option:`-S` switch
690 .. code-block:: python
704 '/www/python/lib/pythonX.Y/plat-linux2', ...]``.
710 be added to ``sys.path``; the :mod:`site` module removes paths that don't
717 .. _inst-config-files:
725 configuration files, which will be consulted before the command-line is parsed.
727 command-line will in turn override configuration files. Furthermore, if
732 .. _inst-config-filenames:
735 ----------------------------------
741 +--------------+----------------------------------------------------------+-------+
745 +--------------+----------------------------------------------------------+-------+
747 +--------------+----------------------------------------------------------+-------+
749 +--------------+----------------------------------------------------------+-------+
753 +--------------+-------------------------------------------------+-------+
757 +--------------+-------------------------------------------------+-------+
759 +--------------+-------------------------------------------------+-------+
761 +--------------+-------------------------------------------------+-------+
764 passing the ``--no-user-cfg`` option.
769 Strictly speaking, the system-wide configuration file lives in the directory
772 :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system
778 standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser`
789 part of the standard library---so the system configuration file would be
800 .. _inst-config-syntax:
803 ----------------------
813 .. code-block:: ini
819 any Python module distribution by any user on the current system. If it is
821 affect only module distributions processed by you. And if it is used as the
822 :file:`setup.cfg` for a particular module distribution, it affects only that
829 .. code-block:: ini
832 build-base=blib
835 which corresponds to the command-line arguments ::
837 python setup.py build --build-base=blib --force
839 except that including the :command:`build` command on the command-line means
846 :option:`!--help` option, e.g.::
848 python setup.py build --help
851 :option:`!--help` without a command::
853 python setup.py --help
858 .. _inst-building-ext:
871 .. _inst-tweak-flags:
874 ------------------------------
880 cross-compile Python.
884 for you to edit. This will likely only be done if the module distribution
889 to build. Each line in a :file:`Setup` describes a single module. Lines have
892 module ... [sourcefile ...] [cpparg ...] [library ...]
897 * *module* is the name of the extension module to be built, and should be a
898 valid Python identifier. You can't just change this in order to rename a module
908 :option:`!-I`, :option:`!-D`, :option:`!-U` or :option:`!-C`.
910 * *library* is anything ending in :file:`.a` or beginning with :option:`!-l` or
911 :option:`!-L`.
915 For example, if the module defined by the line ::
920 :option:`!-lm` to the line::
922 foo foomodule.c -lm
925 the :option:`!-Xcompiler` *arg* and :option:`!-Xlinker` *arg* options::
927 foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
929 The next option after :option:`!-Xcompiler` and :option:`!-Xlinker` will be
931 be passed the :option:`!-o32` option, and the linker will be passed
932 :option:`!-shared`. If a compiler option requires an argument, you'll have to
933 supply multiple :option:`!-Xcompiler` options; for example, to pass ``-x c++``
934 the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``.
941 .. _inst-non-ms-compilers:
943 Using non-Microsoft compilers on Windows
944 ----------------------------------------
961 .. Should we mention that users have to create cfg-files for the compiler?
984 python setup.py build --compiler=bcpp
987 this in your personal or system-wide configuration file for Distutils (see
988 section :ref:`inst-config-files`.)
998 Document describing how to use Borland's free command-line C++ compiler to build
1016 python setup.py build --compiler=cygwin
1018 and for Cygwin in no-cygwin mode [#]_ or for MinGW type::
1020 python setup.py build --compiler=mingw32
1023 consider writing it in your personal or system-wide configuration file for
1024 Distutils (see section :ref:`inst-config-files`.)
1030 binutils-2.13.90-20030111-1).
1038 .. I don't understand what the next line means. --amk
1052 /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
1071 .. [#] This also means you could replace all existing COFF-libraries with OMF-libraries