Lines Matching +full:build +full:- +full:with +full:- +full:python
3 .. _install-index:
6 Installing Python Modules (Legacy version)
16 removed in Python 3.12. This documentation is retained as a
17 reference only, and will be removed with the package. See the
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
31 extensions that are provided as part of this version of Python. Third party
33 recommendations section <https://packaging.python.org/guides/tool-recommendations/>`__
34 in the Python Packaging User Guide for more information.
37 .. _inst-intro:
43 In Python 2.0, the ``distutils`` API was first added to the standard library.
44 This provided Linux distro maintainers with a standard way of converting
45 Python projects into Linux distro packages, and system administrators with a
48 In the many years since Python 2.0 was released, tightly coupling the build
51 ``pip`` package installer and the ``setuptools`` build system, rather than
54 See :ref:`installing-index` and :ref:`distributing-index` for more details.
59 .. _inst-new-standard:
62 ------------------------------------
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
75 python setup.py install
78 (:menuselection:`Start --> Accessories`)::
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
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 --------------------
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
142 python setup.py build
143 python setup.py install
146 first runs the :command:`build` command, which---in this case---quickly notices
147 that it has nothing to do, since everything in the :file:`build` directory is
148 up-to-date.
152 tasks. If you get into distributing your own Python modules and extensions,
156 .. _inst-how-build-works:
159 ------------------
161 As implied above, the :command:`build` command is responsible for putting the
162 files to install into a *build directory*. By default, this is :file:`build`
163 under the distribution root; if you're excessively concerned with speed, or want
164 to keep the source tree pristine, you can change the build directory with the
165 :option:`!--build-base` option. For example::
167 python setup.py build --build-base=/path/to/pybuild/foo-1.0
169 (Or you could do this permanently with a directive in your system or personal
170 Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this
173 The default layout for the build tree is as follows::
175 --- build/ --- lib/
177 --- build/ --- lib.<plat>/
181 platform and Python version. The first form, with just a :file:`lib` directory,
182 is used for "pure module distributions"---that is, module distributions that
183 include only pure Python modules. If a module distribution contains any
184 extensions (modules written in C/C++), then the second form, with two ``<plat>``
188 contains all Python modules (pure Python and extensions) that will be installed.
190 In the future, more directories will be added to handle Python scripts,
192 of installing Python modules and applications.
195 .. _inst-how-install-works:
198 ----------------------
200 After the :command:`build` command runs (whether you run it explicitly, or the
203 :file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation
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
209 by how you built/installed Python itself. On Unix (and macOS, which is also
210 Unix-based), it also depends on whether the module distribution being installed
211 is pure Python or contains extensions ("non-pure"):
215 +-----------------+-----------------------------------------------------+--------------------------…
218 | Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/pyt…
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 +-----------------+-----------------------------------------------------+--------------------------…
228 Most Linux distributions include Python as a standard part of the system, so
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`.
235 Files\\Python` under Python 1.6a1, 1.5.2, and earlier.
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
240 can find out what your Python installation uses for :file:`{prefix}` and
241 :file:`{exec-prefix}` by running Python in interactive mode and typing a few
242 simple commands. Under Unix, just type ``python`` at the shell prompt. Under
243 Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
244 Python (command line)`. Once the interpreter is started, you type Python code
245 at the prompt. For example, on my Linux system, I type the three Python
247 :file:`{prefix}` and :file:`{exec-prefix}`:
249 .. code-block:: pycon
251 Python 2.4 (#26, Aug 7 2004, 17:19:02)
260 version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by
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:
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
283 part of your local Python installation. This is especially true when upgrading
285 scripts still works with the new version before actually upgrading.
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
313 as :file:`{userbase}` hereafter). This scheme installs pure Python modules and
320 modules :file:`{userbase}/lib/python{X.Y}/site-packages`
323 C headers :file:`{userbase}/include/python{X.Y}{abiflags}/{distname}`
331 modules :file:`{userbase}\\Python{XY}\\site-packages`
332 scripts :file:`{userbase}\\Python{XY}\\Scripts`
334 C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}`
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 ---------------------------------------
354 The idea behind the "home scheme" is that you build and maintain a personal
355 stash of Python modules. This scheme's name is derived from the idea of a
363 python setup.py install --home=<dir>
365 where you can supply any directory you like for the :option:`!--home` option. On
369 python setup.py install --home=~
371 To make Python find the distributions installed with this scheme, you may have
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
382 modules :file:`{home}/lib/python`
385 C headers :file:`{home}/include/python/{distname}`
388 (Mentally replace slashes with backslashes if you're on Windows.)
391 .. _inst-alt-install-prefix-unix:
394 ------------------------------------------------
396 The "prefix scheme" is useful when you wish to use one Python installation to
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
399 something that looks like a different Python installation). If this sounds a
400 trifle unusual, it is---that's why the user and home schemes come before. However,
403 First, consider that many Linux distributions put Python in :file:`/usr`, rather
405 since in those cases Python is part of "the system" rather than a local add-on.
406 However, if you are installing Python modules from source, you probably want
408 :file:`/usr/lib/python2.{X}`. This can be done with ::
410 /usr/bin/python setup.py install --prefix=/usr/local
414 Python interpreter accessed as :file:`/usr/local/bin/python` might search for
417 be done with ::
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`
435 C headers :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}`
438 There is no requirement that :option:`!--prefix` or :option:`!--exec-prefix`
439 actually point to an alternate Python installation; if the directories listed
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,
449 Note that installing extensions to an alternate Python installation has no
450 effect on how those extensions are built: in particular, the Python header files
451 (:file:`Python.h` and friends) installed with the Python interpreter used to run
454 in this way is compatible with the interpreter used to build them. The best way
455 to do this is to ensure that the two interpreters are the same version of Python
456 (possibly different builds, or possibly copies of the same build). (Of course,
457 if your :option:`!--prefix` and :option:`!--exec-prefix` don't even point to an
458 alternate Python installation, this is immaterial.)
461 .. _inst-alt-install-prefix-windows:
464 ---------------------------------------------------
466 Windows has no concept of a user's home directory, and since the standard Python
467 installation under Windows is simpler than under Unix, the :option:`!--prefix`
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
477 pure Python modules and extension modules are installed into the same location.
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
501 To create a custom installation scheme, you start with one of the alternate
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
523 difference between Python and extension modules.)
526 under Unix---but you want scripts to go in :file:`~/scripts` rather than
527 :file:`~/bin`. As you might expect, you can override this directory with the
528 :option:`!--install-scripts` option; in this case, it makes most sense to supply
532 python setup.py install --home=~ --install-scripts=scripts
534 Another Unix example: suppose your Python installation was built and installed
535 with a prefix of :file:`/usr/local/python`, so under a standard installation
536 scripts will wind up in :file:`/usr/local/python/bin`. If you want them in
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
550 to worry about, Python and extension modules, which can conveniently be both
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
559 Python's search path.
563 supply relative paths; for example, if you want to maintain all Python
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
588 into your Distutils config file (see section :ref:`inst-config-files`):
590 .. code-block:: ini
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
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
617 want to supply an installation base of :file:`/tmp/python`.)
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:
642 Modifying Python's Search Path
643 ------------------------------
645 When the Python interpreter executes an :keyword:`import` statement, it searches
646 for both Python code and extension modules along a search path. A default value
647 for the path is configured into the Python binary when the interpreter is built.
651 $ python
652 Python 2.2 (#11, Oct 3 2002, 13:31:27)
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/`
684 A slightly less convenient way is to edit the :file:`site.py` file in Python's
686 imported when the Python interpreter is executed, unless the :option:`-S` switch
690 .. code-block:: python
693 sys.path.append('/www/python/')
695 However, if you reinstall the same major version of Python (perhaps when
701 :envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python
702 installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``,
703 the search path will be set to ``['', '/www/python/lib/pythonX.Y/',
704 '/www/python/lib/pythonX.Y/plat-linux2', ...]``.
708 set to ``/www/python:/opt/py``, the search path will begin with
709 ``['/www/python', '/opt/py']``. (Note that directories must exist in order to
713 Finally, ``sys.path`` is just a regular Python list, so any Python application
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 +--------------+----------------------------------------------------------+-------+
744 | system | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) |
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
770 where the Distutils are installed; under Python 1.6 and later on Unix, this is
771 as shown. For Python 1.5.2, the Distutils will normally be installed to
772 :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system
773 configuration file should be put there under Python 1.5.2.
777 home directory will be determined with the :func:`getpwuid` function from the
785 (See also note (1).) Under Python 1.6 and later, Python's default "installation
786 prefix" is :file:`C:\\Python`, so the system configuration file is normally
787 :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the
788 default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not
789 part of the standard library---so the system configuration file would be
790 :file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python
800 .. _inst-config-syntax:
803 ----------------------
813 .. code-block:: ini
819 any Python module distribution by any user on the current system. If it is
825 You could override the default "build base" directory and make the
826 :command:`build\*` commands always forcibly rebuild all files with the
829 .. code-block:: ini
831 [build]
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
855 See also the "Reference" section of the "Distributing Python Modules" manual.
858 .. _inst-building-ext:
864 available by the Python interpreter used to run the :file:`setup.py` script.
865 For example, the same compiler and linker flags used to compile Python will also
871 .. _inst-tweak-flags:
874 ------------------------------
876 Compiling a Python extension written in C or C++ will sometimes require
880 cross-compile Python.
889 to build. Each line in a :file:`Setup` describes a single module. Lines have
898 valid Python identifier. You can't just change this in order to rename a module
907 * *cpparg* is an argument for the C preprocessor, and is anything starting with
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`.
914 add it by editing the :file:`Setup` file and running ``python setup.py build``.
919 must be linked with the math library :file:`libm.a` on your platform, simply add
920 :option:`!-lm` to the line::
922 foo foomodule.c -lm
924 Arbitrary switches intended for the compiler or the linker can be supplied with
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 ----------------------------------------
953 This subsection describes the necessary steps to use Distutils with the Borland
955 format (OMF) is different from the format used by the Python version you can
956 download from the Python or ActiveState web site. (Python is built with
958 reason you have to convert Python's library :file:`python25.lib` into the
961 .. Should we mention that users have to create cfg-files for the compiler?
968 The :file:`coff2omf` program comes with the Borland compiler. The file
969 :file:`python25.lib` is in the :file:`Libs` directory of your Python
976 How does Distutils manage to use these libraries with their changed names? If
978 finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then
982 To let Distutils compile your extension with Borland C++ you now have to type::
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`.)
997 …`Creating Python Extensions Using Borland's Free Compiler <http://www.cyberus.ca/~g_will/pyExtenDL…
998 Document describing how to use Borland's free command-line C++ compiler to build
999 Python.
1005 This section describes the necessary steps to use Distutils with the GNU C/C++
1006 compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter
1007 that was built with Cygwin, everything should work without any of these
1010 Not all extensions can be built with MinGW or Cygwin, but many can. Extensions
1014 To let Distutils compile your extension with Cygwin you have to type::
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`.)
1026 Older Versions of Python and MinGW
1028 The following instructions only apply if you're using a version of Python
1029 inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with
1030 binutils-2.13.90-20030111-1).
1034 you have to create a list of symbols which the Python DLL exports. (You can find
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
1055 :file:`python25.lib`. (Should be the :file:`libs` directory under your Python
1065 …`Building Python modules on MS Windows platform with MinGW <https://old.zope.dev/Members/als/tips/…
1071 .. [#] This also means you could replace all existing COFF-libraries with OMF-libraries