ModuleNotFoundError: No module named distutils.msvccompiler on Windows
Upgrade pip, setuptools, and wheel, and install pre-built binary wheels instead of legacy source packages requiring distutils.
Root Cause Analysis
This error occurs when Python tries to import the legacy distutils.msvccompiler module during C-extension compilation on Windows, following the total removal of distutils from the Python standard library in Python 3.12 (PEP 632).
1. Complete Removal of distutils in Python 3.12
The distutils package was deprecated in Python 3.10 and completely removed in Python 3.12. Older build systems for scientific packages like NumPy, SciPy, and Cython that hardcoded imports from distutils.msvccompiler to configure Microsoft Visual C++ compilers fail immediately.
2. Legacy Package Source Distributions
When installing older versions of scientific libraries via pip install numpy<1.24 under Python 3.12, no compatible pre-built wheel exists on PyPI. Pip attempts to build the package from source using the legacy setup.py script, which attempts to import distutils.msvccompiler and crashes.
3. Modern Build Backends (Meson and Setuptools)
Modern scientific libraries have migrated to Meson (meson-python) or updated setuptools build backends that do not rely on standard library distutils.
4. Virtual Environment Isolation
Running in an environment without setuptools installed exacerbates this issue, as setuptools includes a bundled compatibility shim for distutils.
Reproduction Code (MCVE)
# **Note de reproductibilité :** Dépend de la version de l'interpréteur Python.
import distutils.msvccompiler
Solution 1: Upgrade Packaging Toolchain and Install Modern Wheels
Ensure pip, setuptools, and wheel are up to date so pre-compiled wheels are utilized without invoking legacy compiler scripts.
import setuptools
import sys
print(f'Python version: {sys.version_info.major}.{sys.version_info.minor}')
print(f'Setuptools version: {setuptools.__version__}')
print('Command to execute in terminal:')
print('python -m pip install --upgrade pip setuptools wheel numpy')
Solution 2: Use Compatible Pre-Compiled Binaries
If compiling custom extensions on Windows, use setuptools' built-in MSVC integration rather than invoking distutils directly.
import sys
from setuptools import Extension, setup
print(f'Running on platform: {sys.platform}')
print('In setup.py, always import setup and Extension from setuptools, never distutils.core.')
A common mistake is trying to copy old distutils folders from a Python 3.11 installation into Python 3.12. This leads to severe internal runtime corruption across the C API. Always update your build dependencies or install modern versions of packages that support Python 3.12+. On Windows, another edge case occurs when Microsoft Visual C++ Build Tools are missing or outdated. Even with modern setuptools, building C extensions requires MSVC v143 or higher. Contrast this error with ModuleNotFoundError: No module named 'setuptools', which simply means setuptools is not installed in the active virtual environment.