distutils.rst 1.93 KB
Newer Older
1 2 3 4
:mod:`distutils` --- Building and installing Python modules
===========================================================

.. module:: distutils
5 6
   :synopsis: Support for building and installing Python modules into an
              existing Python installation.
7

8 9
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

10
--------------
11 12 13 14 15 16

The :mod:`distutils` package provides support for building and installing
additional modules into a Python installation.  The new modules may be either
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.

17
Most Python users will *not* want to use this module directly, but instead
18 19
use the cross-version tools maintained by the Python Packaging Authority. In
particular,
20
`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ is an
21 22 23 24 25 26 27 28 29 30 31 32 33 34
enhanced alternative to :mod:`distutils` that provides:

* support for declaring project dependencies
* additional mechanisms for configuring which files to include in source
  releases (including plugins for integration with version control systems)
* the ability to declare project "entry points", which can be used as the
  basis for application plugin systems
* the ability to automatically generate Windows command line executables at
  installation time rather than needing to prebuild them
* consistent behaviour across all supported Python versions

The recommended `pip <https://pip.pypa.io/>`__ installer runs all
``setup.py`` scripts with ``setuptools``, even if the script itself only
imports ``distutils``. Refer to the
35
`Python Packaging User Guide <https://packaging.python.org>`_ for more
36
information.
37

38 39 40 41
For the benefits of packaging tool authors and users seeking a deeper
understanding of the details of the current packaging and distribution
system, the legacy :mod:`distutils` based user documentation and API
reference remain available:
42

43 44
* :ref:`install-index`
* :ref:`distutils-index`