How can one fully replace distutils, which is deprecated in 3.10?

Question

According to PEP 632, distutils will be formally marked as deprecated, and in Python 3.12, it will be removed. My product is soon going to support Python 3.10 and I don't want to put up with deprecation warnings, so I would like to remove references to distutils now.

However, I can't find clear documentation about how to do this properly. The Migration Advice in the PEP is surprisingly sketchy, and I haven't found standard documentation for distutils, or for whatever modules (such as setuptools?) that are required to replace distutils, that would let me fill in the gaps. Nor was I able to figure it out myself from the source code.

Specifically, the "Migration Advice" section says:

For these modules or types, setuptools is the best substitute:

• distutils.ccompiler
• distutils.cmd.Command
• distutils.command
• distutils.config
• distutils.core.Distribution
• distutils.errors

...

For these modules or functions, use the standard library module shown:

...

• distutils.util.get_platform — use the platform module

How exactly does substituting setuptools work? For example, should code like import distutils.command be replaced with import setuptools.command? Meanwhile, what should I do about uses of distutils.core.setup and distutils.core.Extension, which aren't listed here?

Furthermore: setuptools does not appear under the modules or index list in the standard documentation, but I do see it in my Lib/site-packages folder. Is it actually part of the standard distribution?

If not, how exactly should setuptools be installed and used? Is it expected to become part of the standard distribution? Are clients expected to install it via Pip before they can run a setup.py script that imports setuptools? Or is the idea that people shouldn't be running setup.py anymore at all?

---

_{This question addresses the problem from the perspective of developing a library. For installing a library, see Why did I get an error ModuleNotFoundError: No module named 'distutils'?.}

Bankable

distutils.core.setup should be replaced by setuptools.setup. For extensions, see setuptools.pypa.io/en/latest/userguide/extension.html – Leila

setuptools is vendored in CPython, along with pip, via the stdlib ensurepip package. setuptools itself is not stdlib. This is a configure option, so you may find in some cases that setuptools is not there. – Bestiality

@aaron Mainly, more detail on how to actually replace distutils with setuptools, on the level of code examples, and explanations of how to use the other standard library modules in the cases described in the migration guide. I'm capable of doing these things, but I don't write answers for Stack Overflow any more, and I feel that the Q&A would be more generally useful with that level of detail available. – Frisby

(It would also be nice to have some elaboration on what exactly is meant by the claim that Setuptools is part of "the standard python.org distribution", and how that differs from being part of the standard library. Like, I get that this means "literally it appears in your filesystem when you install Python"; but I'm talking about details like how it's bootstrapped into virtual environments etc. And once we have that sort of information in an answer, we can clean up the comment section.) – Frisby

Quite a long related discussion on deprecating distutils module. – Zaremski

Answer 1

• Yes, setuptools can fully replace distutils for everything.
• distutils.core.setup maps to setuptools.setup.
• distutils.core.Extension maps to setuptools.Extension.
• setuptools is not part of The Python Standard Library (hence its absence from the doc) but it is part of the standard python.org distribution.
• Some distributions choose to separate setuptools and pip from the default Python package because they don't assume you will be using Python for writing code, however some system tools require Python (apt among others). If you plan to use the distribution as a development tool, you are expected to install pip and setuptools from the distribution repositories.

Cacodyl