PEP: 632

Title: Deprecate distutils module

Author: Steve Dower <steve.dower@python.org>

Status: Draft

Type: Standards Track

Content-Type: text/x-rst

Created: 03-Sep-2020

Post-History:

Abstract

The distutils module [1]_ has for a long time recommended using the

setuptools package [2]_ instead. Setuptools has recently integrated a

complete copy of distutils and is no longer dependent on the standard

library [3]_. Pip has silently replaced distutils with setuptools when

building packages for a long time already. It is time to remove it

from the (public part of the) standard library.

Motivation

distutils [1]_ is a largely undocumented and unmaintained collection

of utilities for packaging and distributing Python packages, including

compilation of native extension modules. It defines a configuration

format that describes a Python distribution and provides the tools to

convert a directory of source code into a source distribution, and

some forms of binary distribution. Because of its place in the

standard library, many updates can only be released with a major

release, and users cannot rely on particular fixes being available.

setuptools [2]_ is a better documented and well maintained enhancement

based on distutils. While it provides very similar functionality, it

is much better able to support users on earlier Python releases, and

can respond to bug reports more quickly. A number of platform-specific

enhancements already exist in setuptools that have not been added to

distutils, and there is been a long-standing recommendation in the

distutils documentation to prefer setuptools.

Historically, setuptools has extended distutils using subclassing and

monkeypatching, but has now taken a copy of the underlying code. [3]_

As a result, the second last major dependency on distutils is gone and

there is no need to keep it in the standard library.

The final dependency on distutils is CPython itself, which uses it to

build the native extension modules in the standard library (except on

Windows). Because this is a CPython build-time dependency, it is

possible to continue to use distutils for this specific case without

it being part of the standard library.

Deprecation and removal will make it obvious that issues should be

fixed in the setuptools project, and will reduce a source of bug

reports and test maintenance that is unnecessary. It will also help

promote the development of alternative build backends, which can now

be supported more easily thanks to PEP 517.

Specification

In Python 3.10 and 3.11, distutils will be formally marked as

deprecated. All known issues will be closed at this time.

``import distutils`` will raise a deprecation warning.

During Python 3.10 and 3.11, uses of distutils within the standard

library may change to use alternative APIs.

In Python 3.12, distutils will no longer be installed by ``make

install`` or any of the first-party distribution. Third-party

redistributors should no longer include distutils in their bundles or

repositories.

This PEP makes no specification on migrating the parts of the CPython

build process that currently use distutils. Depending on

contributions, this migration may occur at any time.

After Python 3.12 is started and when the CPython build process no

longer depends on distutils being in the standard library, the entire

``Lib/distutils`` directory and ``Lib/test/test_distutils.py`` file

will be removed from the repository.

Other references to distutils will be cleaned up. As of Python 3.9's

initial release, the following modules have references in code or

comments:

* Lib/ctypes/util.py

* Lib/site.py

* Lib/sysconfig.py

* Lib/_aix_support.py

* Lib/_bootsubprocess.py

* Lib/_osx_support.py

* Modules/_decimal/tests/formathelper.py

As the distutils code is already included in setuptools, there is no

need to republish it in any other form. Those who require access to

the functionality should use setuptools or an alternative build

backend.

Backwards Compatibility

Code that imports distutils will no longer work from Python 3.12.

The suggested migration path is to use the equivalent (though not

identical) imports from setuptools.

Compatibility shims already exist in setuptools and pip to

transparently migrate old code, however, these are controlled by

external projects and are in no way bound by this PEP. Consult their

latest documentation for migration advice.

Some projects use alternate sets of shims over distutils, notably,

numpy.distutils. [4]_ Where known, these projects have been informed.

Many use custom commands or more narrowly scoped patches, mostly

constrained to ``setup.py`` files. As these packages are already

subject to setuptools being injected by pip, we expect minimal

disruption as a result of distutils being removed.

Reference Implementation

setuptools version 48 includes the complete copy of distutils, and as

such is no longer dependent on the standard library's copy. Most

implementation issues they have faced are due to the continuing

existence of distutils in the standard library, and so removal will

improve the stability of their implementation.

There is not yet a reference implementation for the removal of

distutils from the standard library, nor is there an implementation

for CPython's native module builds without relying on the standard

library copy of distutils.

References

.. [1] distutils - Building and installing Python modules

.. [2] setuptools - PyPI

.. [3] setuptools Issue #417 - Adopt distutils

.. [4] Packaging (numpy.distutils)

Copyright

This document is placed in the public domain or under the

CC0-1.0-Universal license, whichever is more permissive.