Problem: ModuleNotFoundError: No module named 'distutils' on Python 3.12+ —— Trove problem library

What you will run into

After moving to Python 3.12+ (incl. 3.13/3.14), running old tools, activating a fresh venv, or importing a new interpreter in PyCharm fails with ModuleNotFoundError: No module named 'distutils'.

Most common in old projects/toolchains: legacy setup.py, old libraries depending on distutils, and fresh venvs that no longer include setuptools by default (since 3.12, venv ships only pip, no setuptools).

Why this happens

Python 3.12 removed distutils from the standard library (deprecated for years before that).

Also, since 3.12 a fresh venv installs only pip by default, no setuptools, and distutils' shim happens to be provided by setuptools — import distutils actually maps to setuptools/_distutils.

The error's essence: "no setuptools in the environment, therefore no distutils shim."

distutils was removed from the standard library in 3.12, but the real mechanism is the "shim": import distutils is actually provided by setuptools' _distutils (setuptools installs a distutils replacement).

Since 3.12, fresh venvs ship with pip only — no setuptools — so "import distutils fails" really means "the environment has no setuptools, hence no shim".

System Python does not fail because distros preinstall setuptools.

Deterministic takeaway: on ModuleNotFoundError: No module named distutils, first check for setuptools (pip show setuptools);

two correct paths — install setuptools (pip install setuptools, shim returns) or migrate to packaging/stdlib alternatives (sysconfig, tomllib); legacy projects should not pin setuptools out of requirements (it is also a build dependency);

fixed diagnostic: the same import works on system Python but fails in a fresh venv = missing setuptools, not a code problem.

Step by step

1. Install setuptools — Required

pip install setuptools

After install, import distutils works again (via the setuptools/_distutils shim).

2. Also upgrade pip/setuptools — Required

python -m ensurepip --upgrade && pip install --upgrade setuptools pip

Old pip (e.g. PyCharm's bundled 20.3.4) is poorly compatible with 3.12+ and often breaks at the same time.

3. System package manager (only for old Python versions) — Required

sudo apt install python3-distutils

Note this package usually only goes up to Python 3.11; distros may not provide it for 3.12+, prefer option 1.

4. Long-term fix (legacy project migration) — Required

Convert old setup.py to pyproject.toml + setuptools.build_meta (PEP 517) and remove direct distutils imports from code. Installing setuptools as a transition lets you move fast, but distutils is EOL and won't come back.

How to confirm it works

Import restored (measured output shape):

After pip install setuptools inside the venv → import distutils works, exit 0 (measured)
Load path becomes the venv's setuptools/_distutils/__init__.py (measured)

Other environments

Symptom

After switching to Python 3.12+ (including 3.13/3.14), running legacy tools, activating a fresh virtualenv, or adding a new interpreter in PyCharm fails with:

ModuleNotFoundError: No module named 'distutils'

Most common in legacy projects/toolchains: old setup.py files using from distutils.core import setup, old libraries depending on distutils, and fresh venvs (since 3.12 a venv ships pip only, no setuptools).

Cause

Python 3.12 removed distutils from the standard library (deprecated for years). In addition, since 3.12 fresh venvs only include pip, no setuptools — and the distutils replacement (shim) is provided by setuptools: import distutils actually maps to setuptools/_distutils. So the error effectively means "no setuptools in this environment, hence no distutils shim".

Solution

In recommended order:

1. Install setuptools (most common, instant fix): pip install setuptools. After that import distutils works again via the setuptools/_distutils shim. Install inside the venv when using one; use sudo pip install setuptools or your system package manager for system Pythons.
2. Also upgrade pip/setuptools: python -m ensurepip --upgrade && pip install --upgrade setuptools pip — old pip versions (e.g. PyCharm's bundled 20.3.4) are poorly compatible with 3.12+ and often fail together.
3. System package manager (Debian/Ubuntu, older Pythons only): sudo apt install python3-distutils. Note this package usually only exists up to Python 3.11; 3.12+ distros may not provide it — prefer option 1.
4. Long-term fix (legacy project migration): convert old setup.py to pyproject.toml + setuptools.build_meta (PEP 517) and remove direct distutils imports. Installing setuptools is a fine stopgap, but distutils is EOL and will not come back.