distutils.util 模块缺失问题解决方案

问题描述

在升级到 Python 3.10 或更高版本后，尝试安装包时遇到错误：

ModuleNotFoundError: No module named 'distutils.util'

即使确认已经安装了 distutils：

sudo apt-get install python3-distutils

系统提示已安装最新版本，但问题依然存在。

根本原因

从 Python 3.12 开始，distutils 模块已被完全移除。根据 PEP 632，该模块在 Python 3.10 中已被标记为弃用，并在 3.12 版本中正式移除。

Python 版本变化

• Python 3.10-3.11: distutils 已弃用（可用但会显示警告）
• Python 3.12+: distutils 已完全移除

解决方案

方法一：安装 setuptools（推荐）

setuptools 包提供了 distutils 的替代功能：

# 通用安装方式
pip install setuptools

# Ubuntu/Debian 系统
sudo apt install python3-setuptools

# macOS (Homebrew)
brew install python-setuptools

如果需要升级已安装的 setuptools：

pip install --upgrade setuptools

方法二：安装特定版本的 distutils

对于 Python 3.10 及之前版本，可以安装特定版本的 distutils：

# 根据你的 Python 版本选择
sudo apt-get install python3.10-distutils  # Python 3.10
sudo apt-get install python3.9-distutils   # Python 3.9
sudo apt-get install python3.8-distutils   # Python 3.8

方法三：重新创建虚拟环境

如果使用虚拟环境，可能需要重新创建：

# 确保使用正确的 Python 路径
virtualenv venv --python=/usr/bin/python3.10 --pip 24.2

方法四：降级 Python 版本

如果项目对 Python 3.12+ 兼容性有问题，可以考虑降级：

# 降级到 Python 3.11 或更早版本
# 然后按照方法二安装对应版本的 distutils

特殊情况处理

Windows 系统问题

在 Windows 上，可能需要：

1. 安装 Visual C++ Build Tools
2. 确保正确设置 Python 路径
3. 使用完整路径创建虚拟环境：

mkvirtualenv -p C:\Python312\python.exe myenv

多版本 Python 共存

当系统中有多个 Python 版本时，确保为正确的版本安装包：

# 明确指定 Python 版本
python3.10 -m pip install setuptools

Ubuntu/Debian 系统额外步骤

某些情况下可能需要安装 venv 模块：

sudo apt install python3.10-venv

验证解决方案

安装完成后，验证问题是否解决：

python3 -c "from distutils.util import strtobool; print('Success')"

如果显示 "Success"，则表示问题已解决。

总结

distutils.util 模块缺失问题主要由 Python 3.12 移除该模块引起。最佳解决方案是安装 setuptools 包，它提供了 distutils 的兼容替代。对于特定环境，可能需要安装版本特定的 distutils 或重新配置虚拟环境。

迁移建议

长期来看，建议迁移到使用 setuptools 或其他现代打包工具，因为 distutils 已被官方弃用并移除。

更多详细信息请参考 PEP 632 迁移指南。