Setuptools has adopted distutils as outlined in [pypa/packaging-problems#127](https://github.com/pypa/packaging-problems/issues/127). Although there are some straggling issues, the current release of Setuptools fully obviates distutils if a certain environment variable is set. Soon, that behavior will be default.

Additionally, the distutils codebase remains maintained at [pypa/distutils](https://github.com/pypa/distutils) in a form suitable for releasing as a third-party package, should the need arise (i.e. pip install distutils).

The plan now is to freeze, deprecate, and in Python N + 0.1, remove distutils.

Already, Setuptools is identifying emergent bugs and other defects in distutils and providing fixes for them (issue41207, [pypa/setuptools#2212](https://github.com/pypa/setuptools/issues/2212)). Keeping these changes in sync across three repos and different supported versions is tedious, so I'd like to move forward with the deprecation process as soon as possible.

Łukasz, would it be possible to add the deprecation warning and documented deprecation to Python 3.9?

So what is the plan to continue to support building cpython itself which depends on Distutils? Currently the build bootstraps itself without the aid of an existing Python interpreter instance. There would also be major impacts across the whole cpython development process. For example, there are many open Distutils issues in the bugs.python.org bug tracker. We need a plan on how those are to be handled (and that should take into account the expected transition from b.p.o to GitHub issues).  People will continue to submit issues agains Distutils there so triage team members and core developers need to know how to handle such issues.  What if an issue applies also or only to a previous release branch (i.e. where Distutils is still in the repo)?  What about Distutils documentation in the Python docset?  THose are just some off the top of my head.

I don't think any of these issues are necessarily blockers but they need to be planned for and reviewed.  I think a PEP is definitely in order for a change of this magnitude.

It's too late to add a new deprecation in the Python 3.9 cycle. Next week is the *last* beta release. Most beta testing already took place.

> So what is the plan to continue to support building cpython itself which depends on Distutils? Currently the build bootstraps itself without the aid of an existing Python interpreter instance. There would also be major impacts across the whole cpython development process.

My understanding was that the plan was to move the standard library distutils into a private module somewhere in the standard library and presumably to slim it down to only the bare minimum required for what is necessary to build Python itself. We're really only concerned with the use of distutils to build packages.

> For example, there are many open Distutils issues in the bugs.python.org bug tracker. We need a plan on how those are to be handled (and that should take into account the expected transition from b.p.o to GitHub issues).  People will continue to submit issues agains Distutils there so triage team members and core developers need to know how to handle such issues. What if an issue applies also or only to a previous release branch (i.e. where Distutils is still in the repo)?

As far as I can tell we've already been telling people that issues in distutils should be fixed in setuptools instead for a few years. I don't think anything needs to be done about the currently open distutils tickets before we *deprecate* distutils, though during the deprecation period we'll probably want to decide whether we want to migrate them, do a mass closure or just leave them to be ad hoc closed as people stumble upon them later. Mass closure may be complicated because tickets affecting CPython itself will still need to be addressed.

> What about Distutils documentation in the Python docset?  THose are just some off the top of my head.

The distutils documentation is already basically just a warning page that says "stop using distutils": https://docs.python.org/3/library/distutils.html#module-distutils

Before these reference materials are removed from the docs we'll need to make sure that all the stuff that's still supported is documented on the setuptools side.

> I don't think any of these issues are necessarily blockers but they need to be planned for and reviewed.  I think a PEP is definitely in order for a change of this magnitude.

A PEP may be a good idea, but I do think the change doesn't have a particularly large magnitude. Anyone using setuptools or pip has already been getting setuptools' monkey-patched version of distutils for ages now, and soon they will be getting setuptools' vendored version. The documentation already indicates that distutils is at least soft-deprecated in favor of setuptools and we've already been directing issues and PRs to setuptools instead of distutils. This last piece is really formalizing something we've been incrementally working towards for a long time now. Doesn't mean we shouldn't do it carefully and with a lot of notice, but it's also not a sudden and massive shift.

Deprecating in 3.10 is fine - everyone who needs to know about it releases whenever they like anyway, so we just need to make _some_ announcement.

I'd propose either moving it to Tools/distutils, or renaming it to _distutils. The point is that we're saying it's only fit for use for the core build now, and nobody else should ever import it (or complain about it ;) ).

Maybe it would make sense to remove distutils from the name completely, _buildutils or something. Dunno, seems like it might be reasonable just to further separate it from the concept of "distutils" the public library.

FYI PEP 387 (which I expect will be accepted once I catch up from vacation) specified deprecations are to be public for two releases before removal or approval from the SC for a shorter cycle.

So if distutils is deprecated in 3.10 then it can be removed in 3.12 or you can ask the SC for an exemption to do it in 3.11.

> It's too late to add a new deprecation in the Python 3.9 cycle

Please can we add a note in 3.9, that it will be deprecated in 3.10?

Renaming distutils to _buildutils only delays the problem to remove it.  But yes, it explicitly makes it explicit that code needs to be changed.

I would like to see that neither distutils or _buildutils is installed by default, and only is available internally for building the extensions of CPython.

The "old" build system to build builtins instead of extensions is still functional, so it should be ok to build the extensions also with the old build system.

That would require moving all the config stuff in setup.py to autoconf tests, which is perfectly doable.  The MacOS and Windows builds would need some attention too, but afaicr when asking Ned Deily and Steve Dower at the language summits, they didn't have a concern about this approach.

+1

I would like to propose three changes:

1) rename distutils, either _distutils or _buildutils sounds good to me
2) make distutils a build-only dependency and no longer install it with make install and other install targets
3) start to build extensions from Makefile or Modules/Setup

For (3) we have to move some checks into autoconf and maybe extend Modules/Setup to support conditional compilation.

> A PEP may be a good idea, but I do think the change doesn't have a
> particularly large magnitude. Anyone using setuptools or pip has
> already been getting setuptools' monkey-patched version of distutils
> for ages now, and soon they will be getting setuptools' vendored
> version. The documentation already indicates that distutils is at
> least soft-deprecated in favor of setuptools and we've already been
> directing issues and PRs to setuptools instead of distutils.

I don't think it's a good idea to replace bad habits from distutils with bad habits in setuptools._distutils.  And this is exactly what you get with pointing directly to setuptools.

While splitting out distutils to a separate package in a Linux distro, I found some creative usages at runtime of a package (see my lightning talk at the language summit 2018, and [1]).  From my point of view, CPython should provide documentation how to forward-port these issues without using setuptools._distutils.

Currently setuptools only has one component (pkg_resources, [2]) which is used at runtime.  I dislike it if more than that is used at runtime of a package.

[1] https://mail.python.org/archives/list/distutils-sig@python.org/thread/74WZ7D3ARF7B3N6MAV2JBV3DW6TRHFIV/
[2] https://github.com/pypa/setuptools/issues/863

The Windows build doesn't depend on distutils at all. We've had dedicated build scripts for each module since before I started contributing.

The Windows build system didn't use setu.py even before I upgrade the VS build system to VS 2010.

> I don't think it's a good idea to replace bad habits from distutils with bad habits in setuptools._distutils.  And this is exactly what you get with pointing directly to setuptools.

These are two different questions. We're not asking people to migrate to `setuptools._distutils` (a private module which may not continue to exist in that location), `setuptools` is *adopting* `distutils`, such that `distutils` is a project provided by `pip install distutils` (mind you, this is happening independent of what the standard library does — the only question is whether `import distutils` continues to work if you don't have `setuptools` installed).

> While splitting out distutils to a separate package in a Linux distro, I found some creative usages at runtime of a package (see my lightning talk at the language summit 2018, and [1]).  From my point of view, CPython should provide documentation how to forward-port these issues without using setuptools._distutils.

At this point, the extent of CPython's documentation on this should probably be, "We are removing `distutils` and moving it into the `setuptools` namespace. In future versions, you will need to install `setuptools` to import the `distutils` package." `setuptools` should almost certainly deprecate `distutils` and probably remove large swathes of it in the process, but that's probably on a case-by-case basis, and it's a separate issue from what needs to happen in CPython.

> Currently setuptools only has one component (pkg_resources, [2]) which is used at runtime.  I dislike it if more than that is used at runtime of a package.

I don't think anyone is planning to recommend the use of *any* `setuptools`-provided packages at runtime, including `pkg_resources`. This move is actually a good one from that point of view, because it will require that projects using `distutils` declare a *runtime* dependency on `setuptools`, which will, hopefully, raise some eyebrows. Better than the current situation, where these dependencies are totally undeclared (though probably worse than if `setuptools`, `pkg_resources` and `distutils` were all separate PyPI packages).

Oops, just realized my previous post said `pip install distutils`. I meant to say that `pip install setuptools` will provide the `distutils` module (right now you do `import setuptools; import distutils` and you get the setuptools-provided version; we're working on a version where `import distutils` comes from `setuptools` regardless of the import order).

I noticed that a new PEP draft [1] about deprecating distutils is uploaded. The current version [2] proposes to deprecate distutils in 3.10 and 3.11 and remove distutils in 3.12.

[1] https://www.python.org/dev/peps/pep-0632/
[2] https://github.com/python/peps/commit/5d5c68517cf9087e104673f7f8322311e31a4e0a

That PR is just to add the import warning and update docs. I want to make sure that's in asap so we don't miss the release.

Is there anywhere else in the docs that needs a note? Distutils has been marked as deprecated for years already, so it's really just emphasising that and adding the 3.12 removal date. I think whatsnew, library and the old doc sections is enough, yeah?

New changeset 62949f697fdefbf0c8bbba7a8354b9376afa35ba by Steve Dower in branch 'master':
bpo-41282: Add deprecation warning and docs for distutils (PEP 632) (GH-24355)
https://github.com/python/cpython/commit/62949f697fdefbf0c8bbba7a8354b9376afa35ba

Everyone probably noticed, but I closed all the other distutils-tagged issues (as stated in the PEP), so now this is the only one left.

Anything new that is opened that relates to distutils either needs to be a release blocker (very unlikely), or closed and directed to setuptools instead.

New changeset 5bfa94560519bbe70ae66ff0a29498f2ae2e1937 by Inada Naoki in branch 'master':
bpo-41282: distutils: Fix stacklevel for DeprecationWarning (GH-24657)
https://github.com/python/cpython/commit/5bfa94560519bbe70ae66ff0a29498f2ae2e1937

I have created below issues where deprecation warning is emitted due to distutils usage in tests. Probably there are other places that need an update to setuptools like setup.py used by make that emits deprecation warning during building cpython.

https://bugs.python.org/issue43426
https://bugs.python.org/issue43425

 rg '(from|import) distutils' | rg -v 'Lib/distutils|rst'
Modules/_decimal/tests/formathelper.py:from distutils.spawn import find_executable
Doc/includes/setup.py:from distutils.core import setup, Extension
Doc/includes/test.py:from distutils.util import get_platform
setup.py:from distutils import log
setup.py:from distutils.command.build_ext import build_ext
setup.py:from distutils.command.build_scripts import build_scripts
setup.py:from distutils.command.install import install
setup.py:from distutils.command.install_lib import install_lib
setup.py:from distutils.core import Extension, setup
setup.py:from distutils.errors import CCompilerError, DistutilsError
setup.py:from distutils.spawn import find_executable
Lib/_osx_support.py:        from distutils import log
Lib/_osx_support.py:    Currently called from distutils.sysconfig
Lib/test/support/__init__.py:    from distutils import ccompiler, sysconfig, spawn, errors
Lib/test/test_distutils.py:import distutils.tests
Lib/test/test_importlib/test_windows.py:from distutils.util import get_platform
Lib/test/test_peg_generator/test_c_parser.py:from distutils.tests.support import TempdirManager
Lib/test/test_sundry.py:            import distutils.bcppcompiler
Lib/test/test_sundry.py:            import distutils.ccompiler
Lib/test/test_sundry.py:            import distutils.cygwinccompiler
Lib/test/test_sundry.py:            import distutils.filelist
Lib/test/test_sundry.py:            import distutils.text_file
Lib/test/test_sundry.py:            import distutils.unixccompiler
Lib/test/test_sundry.py:            import distutils.command.bdist_dumb
Lib/test/test_sundry.py:                import distutils.command.bdist_msi
Lib/test/test_sundry.py:            import distutils.command.bdist
Lib/test/test_sundry.py:            import distutils.command.bdist_rpm
Lib/test/test_sundry.py:            import distutils.command.build_clib
Lib/test/test_sundry.py:            import distutils.command.build_ext
Lib/test/test_sundry.py:            import distutils.command.build
Lib/test/test_sundry.py:            import distutils.command.clean
Lib/test/test_sundry.py:            import distutils.command.config
Lib/test/test_sundry.py:            import distutils.command.install_data
Lib/test/test_sundry.py:            import distutils.command.install_egg_info
Lib/test/test_sundry.py:            import distutils.command.install_headers
Lib/test/test_sundry.py:            import distutils.command.install_lib
Lib/test/test_sundry.py:            import distutils.command.register
Lib/test/test_sundry.py:            import distutils.command.sdist
Lib/test/test_sundry.py:            import distutils.command.upload
Tools/peg_generator/pegen/build.py:    import distutils.log
Tools/peg_generator/pegen/build.py:    from distutils.core import Distribution, Extension
Tools/peg_generator/pegen/build.py:    from distutils.command.clean import clean  # type: ignore
Tools/peg_generator/pegen/build.py:    from distutils.command.build_ext import build_ext  # type: ignore
Tools/peg_generator/pegen/build.py:    from distutils.tests.support import fixup_build_ext  # type: ignore
Tools/c-analyzer/c_parser/preprocessor/common.py:import distutils.ccompiler
Tools/c-analyzer/c_parser/preprocessor/__init__.py:import distutils.ccompiler
Tools/test2to3/setup.py:from distutils.core import setup
Tools/test2to3/setup.py:    from distutils.command.build_py import build_py_2to3 as build_py
Tools/test2to3/setup.py:    from distutils.command.build_py import build_py
Tools/test2to3/setup.py:    from distutils.command.build_scripts import build_scripts_2to3 as build_scripts
Tools/test2to3/setup.py:    from distutils.command.build_scripts import build_scripts
Tools/test2to3/test/runtests.py:    from distutils.util import copydir_run_2to3
Misc/HISTORY:- Issue #5394: removed > 2.3 syntax from distutils.msvc9compiler.

New changeset d9ba9dee7f267a603394b8d63a7697b08efdf1cb by Victor Stinner in branch 'master':
bpo-41282: setup.py ignores distutils DeprecationWarning (GH-25405)
https://github.com/python/cpython/commit/d9ba9dee7f267a603394b8d63a7697b08efdf1cb

New changeset 341e8a939aca6e9f59ffb0e6daee5888933694ed by Lumír 'Frenzy' Balhar in branch 'master':
bpo-41282: (PEP 632) Load install schemes from sysconfig (GH-24549)
https://github.com/python/cpython/commit/341e8a939aca6e9f59ffb0e6daee5888933694ed

New changeset 69ca32e0d34fe17dd242592b6f8754cda7bae684 by Victor Stinner in branch 'master':
bpo-41282: Fix distutils.utils.byte_compile() DeprecationWarning (GH-25406)
https://github.com/python/cpython/commit/69ca32e0d34fe17dd242592b6f8754cda7bae684

New changeset 90d02e5e63e2cb8f66a2c0dd2ea8d7d4f45f4ebf by Lumír 'Frenzy' Balhar in branch 'master':
bpo-41282: (PEP 632) Deprecate distutils.sysconfig (partial implementation of the PEP) (GH-23142)
https://github.com/python/cpython/commit/90d02e5e63e2cb8f66a2c0dd2ea8d7d4f45f4ebf

New changeset a460ab3134cd5cf3932c2125aec012851268f0cc by Christian Heimes in branch 'master':
bpo-41282: Consistent message and filter warning in setup.py (GH-25571)
https://github.com/python/cpython/commit/a460ab3134cd5cf3932c2125aec012851268f0cc

PR 25718 was opened and linked to this ticket.  It changes sysconfig to load install schemes from a separate module, so it’s not strictly about removing distutils but adding a new system customization feature.  I think it needs its own bug and mailing-list discussion with interested parties to make sure the interface works for them.

That is reasonable. I have created bpo-43976.

I'd suggest also posting it on the Packaging discourse, to get feedback from other distro maintainers.

We have discussed this approach a little in a few bug trackers, but I opened https://discuss.python.org/t/mechanism-for-distributors-to-add-site-install-schemes-to-python-installations/8467.

Hello everyone, 

How are we supposed to use get_python_lib now (a function that returned the site-packages location)?

`from setuptools._distutils.sysconfig import get_python_lib` doesn't really seem like the right solution and the sysconfig stdlib module doesn't have any get_python_lib function.

I believe sysconfig.get_path('purelib') and sysconfig.get_path('platlib') should work for you.

> sysconfig.get_path('purelib')
/usr/lib/python3.9/site-packages
> sysconfig.get_path('platlib')
/usr/lib/python3.9/site-packages

(here it's the same path, but it is not guaranteed to be)

That seems fine, tho for some of distros that do lots of python customizations (tried the docker ubuntu image for 18.04.3) it get a bit strange:

Python 3.6.9 (default, Jan 26 2021, 15:33:00)
[GCC 8.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import sysconfig
>>> import distutils.sysconfig
>>> sysconfig.get_path('platlib')
'/usr/lib/python3.6/site-packages'
>>> sysconfig.get_path('purelib')
'/usr/lib/python3.6/site-packages'
>>> distutils.sysconfig.get_python_lib()
'/usr/lib/python3/dist-packages'

If you are relying on the value of distutils.sysconfig.get_python_lib() as you shown in your system, you probably don't want to. That directory (dist-packages) should be for Debian provided packages only, so moving to sysconfig.get_path() would be a good thing, as it has the correct value for user installed packages on your system.

But anyway, there have been introduced mechanisms that should allow distros to deal with these issues. The goal is to make it so that distros can officially customize such details and not have to rely on heavy patching.

Alright so to get all the package paths, included distro-managed ones would be this right?

for scheme in sysconfig.get_scheme_names():
 for name in ['purelib', 'platlib']:
  sysconfig.get_path(name, scheme)

That always depends on the way distros patch Python, though all the major distros I know will add their schemes to sysconfig, which works what that approach. But yeah, that is what you probably want to be doing :)

It looks like 341e8a939aca6e9f59ffb0e6daee5888933694ed (GH-24549) incorrectly deleted an important check in sysconfig that is needed for building the cpython standard library on unix-y systems. The chain of events is somewhat complicated but the problem can be easily seen by carefully examining the output of a simple build and install, like:

./configure --prefix=/tmp/testbuild
make
make install

As of 3.10.0b1, this results in the standard library module being built twice, once by the make step and once by the make install step.

GH-26237 attempts to fix the problem with minimal changes to the approach taken in GH-24549 to consolidate Lib/sysconfig.py and Lib/distutils/sysconfig.py. Frankly, I am not confident it is the best approach so it should be carefully reviewed. There probably should also be a test added at some point for this case but I will let someone else deal with that and a test should not hold up 3.10.0b2. But I think the build failure is serious enough that b2 should be held for a fix.

Er, make that "GH-26327 attempts to fix the problem ... " but I see from the CI that it causes test_distutils to fail in the simpler case of running the test from the build directory (rather than from an installed location which does pass). I have run out of time right now but I will get back to it later today unless someone gets to it first.

When building Python, we need two distinct "include" directories:
- source .h files
- install target for .h files

Note that this doesn't matter except when building Python from source.

Historically:
- source .h files were in the sysconfig scheme under 'include'
- the install directory was in the distutils.command.install scheme
    under 'headers'

GH-24549 merged these, because sysconfig is now the single source of truth and distutils is derived from it.
It seems to me that we need to bring 'headers' back -- at least when building Python.

New changeset 1c454eb2e4eb9e08ee94920c0e1ca7c8896371ec by Miss Islington (bot) in branch '3.10':
bpo-41282: Fix broken `make install` (GH-26329)
https://github.com/python/cpython/commit/1c454eb2e4eb9e08ee94920c0e1ca7c8896371ec

Petr's analysis and PR looked good and the PR is now merged to main and to 3.10 for 3.10.0b2.  Thanks, Petr! Downgrading back to normal priority.

Thank you for doing the hard part, Ned!

Related: https://bugs.python.org/issue45460