Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`distutils` --- Building and installing Python modules |
| 2 | =========================================================== |
| 3 | |
| 4 | .. module:: distutils |
Georg Brandl | 71515ca | 2009-05-17 12:29:12 +0000 | [diff] [blame] | 5 | :synopsis: Support for building and installing Python modules into an |
| 6 | existing Python installation. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| 8 | |
| 9 | |
| 10 | The :mod:`distutils` package provides support for building and installing |
| 11 | additional modules into a Python installation. The new modules may be either |
| 12 | 100%-pure Python, or may be extension modules written in C, or may be |
| 13 | collections of Python packages which include modules coded in both Python and C. |
| 14 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 15 | Most Python users will *not* want to use this module directly, but instead |
Nick Coghlan | 3894ae2 | 2014-10-26 00:00:04 +1000 | [diff] [blame] | 16 | use the cross-version tools maintained by the Python Packaging Authority. In |
| 17 | particular, |
| 18 | `setuptools <https://setuptools.pypa.io/en/latest/setuptools.html>`__ is an |
| 19 | enhanced alternative to :mod:`distutils` that provides: |
| 20 | |
| 21 | * support for declaring project dependencies |
| 22 | * additional mechanisms for configuring which files to include in source |
| 23 | releases (including plugins for integration with version control systems) |
| 24 | * the ability to declare project "entry points", which can be used as the |
| 25 | basis for application plugin systems |
| 26 | * the ability to automatically generate Windows command line executables at |
| 27 | installation time rather than needing to prebuild them |
| 28 | * consistent behaviour across all supported Python versions |
| 29 | |
| 30 | The recommended `pip <https://pip.pypa.io/>`__ installer runs all |
| 31 | ``setup.py`` scripts with ``setuptools``, even if the script itself only |
| 32 | imports ``distutils``. Refer to the |
Georg Brandl | e73778c | 2014-10-29 08:36:35 +0100 | [diff] [blame] | 33 | `Python Packaging User Guide <https://packaging.python.org>`_ for more |
Nick Coghlan | 3894ae2 | 2014-10-26 00:00:04 +1000 | [diff] [blame] | 34 | information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 35 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 36 | For the benefits of packaging tool authors and users seeking a deeper |
| 37 | understanding of the details of the current packaging and distribution |
| 38 | system, the legacy :mod:`distutils` based user documentation and API |
| 39 | reference remain available: |
Éric Araujo | 55729fe | 2011-06-02 15:45:25 +0200 | [diff] [blame] | 40 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 41 | * :ref:`install-index` |
| 42 | * :ref:`distutils-index` |