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