ModuleNotFoundError: No module named distutils after python 3.12 upgrade

ModuleNotFoundError: No module named distutils after python 3.12 upgrade

TL;DR: Python 3.12 removed the long-deprecated distutils module. Replace the import with its modern equivalent (sysconfig, shutil, or packaging), or install setuptools as a bridge - it ships a distutils shim. Whether you patch your code or add the shim depends on who owns the import.

ModuleNotFoundError: No module named distutils after python 3.12 upgrade

Steps

1. Find the import: run the failing command and read the traceback for the import distutils / from distutils... line. Note whether it is your code or a third-party package. Expected: you know the exact file, line, and owner of the import.

2. If it is your code, replace it: distutils.sysconfig becomes sysconfig, directory utilities become shutil, version parsing becomes packaging.version. Expected: the module imports cleanly with no distutils reference left.

3. If it is a dependency, upgrade that package first (pip install -U [package-name]). If no fixed release exists, pip install setuptools restores distutils as a compatibility shim. Expected: the import resolves and the original command runs.

4. Verify: import the module directly and re-run the original command. Expected: no ModuleNotFoundError.

Use this when

• The error names distutils and python --version shows 3.12+.
• An old setup.py, vendored helper, or pinned dependency still imports distutils.
• The same code worked on Python 3.11.

Not for this skill when

• You are on Python 3.11 or older - distutils still exists there (deprecated but importable).
• The missing module is something else that merely resembles a stdlib removal - check the name.
• The error is No module named setuptools - install setuptools itself, different problem.

Variant phrasings

• python 3.12 distutils removed ModuleNotFoundError
• import distutils fails after python upgrade
• setuptools distutils shim python 3.12

Why it happens

distutils was deprecated since Python 3.10 and removed in 3.12. Setuptools vendors a copy and installs it as a fallback shim, which is why adding setuptools masks the error - but the stdlib module itself is gone for good.

Edge cases

• The setuptools shim prints a deprecation warning and will itself go away - treat it as a bridge while you fix the real import, not a permanent fix.
• Some Linux distros package setuptools separately from Python - you may need the distro package or pip install, whichever your environment uses.
• If a pinned dependency is the importer and cannot be upgraded, the shim is your only option short of vendoring a patched copy.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CES8lCLNIrHRslmxHt2BnQ