Fixing 'No module named distutils.util' Error

Problem Overview

A common but confusing error occurs when upgrading Python versions or installing packages with pip:

ModuleNotFoundError: No module named 'distutils.util'

This error typically appears when trying to install Python packages like opencv-python, even when the system indicates that distutils is already installed.

Root Cause

The distutils module was deprecated in Python 3.10 and completely removed in Python 3.12 as part of PEP 632. This means:

• Python 3.10-3.11: distutils available but deprecated (with warnings)
• Python 3.12+: distutils completely removed from standard library

pip and other tools still rely on distutils functionality, which is now provided by the setuptools package.

Solutions

Primary Solution: Install setuptools

The most reliable fix for all Python versions is to install setuptools:

pip install setuptools

If you have multiple Python versions installed, specify the correct pip executable:

python3.12 -m pip install setuptools

TIP

For virtual environments created with Python 3.12+, setuptools is no longer pre-installed. Always run pip install setuptools after creating a new virtual environment.

Platform-Specific Installations

Ubuntu/Debian Systems

sudo apt install python3-setuptools

For specific Python versions:

sudo apt install python3.10-distutils  # For Python 3.10
sudo apt install python3.11-distutils  # For Python 3.11

macOS (Homebrew)

brew install python-setuptools

Windows

Ensure you have the correct Python version selected in your PATH, then:

pip install setuptools

WARNING

On Windows with multiple Python installations, use the specific Python executable:

py -3.12 -m pip install setuptools

Virtual Environment Solutions

When creating virtual environments with Python 3.12+, ensure proper setup:

# Create venv with explicit Python version
python3.12 -m venv myenv

# Activate and install setuptools
source myenv/bin/activate  # Linux/macOS
# or
myenv\Scripts\activate     # Windows

pip install setuptools

Alternative: Downgrade Python Version

If compatibility issues persist, consider using Python 3.11 or earlier:

# Ubuntu/Debian example
sudo apt install python3.11
python3.11 -m pip install your-package

Advanced Scenarios

Multiple Python Versions

When multiple Python versions are installed, ensure you're using the correct pip:

# Check which Python version you're using
python --version

# Install setuptools for that specific version
python -m pip install setuptools

Virtual Environment with Specific pip Version

For complex environments (like on Raspberry Pi), specify pip version:

virtualenv myenv --python=python3.12 --pip 24.2

Reinstalling distutils (Python < 3.12)

For Python 3.10-3.11, you can reinstall the distutils package:

sudo apt-get install --reinstall python3.11-distutils

Prevention and Best Practices

1. Always install setuptools in virtual environments before other packages
2. Use version-specific Python commands when multiple versions are installed
3. Keep pip updated: python -m pip install --upgrade pip
4. Check Python version compatibility before installing packages

Warning for Python 3.12+ Users

Distutils has been completely removed from Python 3.12. The only supported solution is to install setuptools. Any suggestions to install distutils packages will not work on Python 3.12.

Additional Resources

• PEP 632 — Deprecate distutils module
• Python 3.12 Release Notes
• setuptools Documentation

By following these solutions, you should be able to resolve the "No module named 'distutils.util'" error and continue with your Python package installations successfully.