# 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.

```text
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