ModuleNotFoundError: No module named 'distutils' の解決方法

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
  <circle cx="12" cy="12" r="10"></circle>
  <line x1="12" y1="8" x2="12" y2="16"></line>
  <line x1="8" y1="12" x2="16" y2="12"></line>
</svg>

問題の本質

Python 3.12でskfuzzyなどのパッケージをインポートしようとすると、次のエラーが発生する場合があります：

ModuleNotFoundError: No module named 'distutils'

このエラーの原因はPython 3.12でのdistutilsモジュールの完全削除にあります。distutilsはPython 3.10で非推奨化され、Python 3.12で標準ライブラリから削除されました（PEP 632）。

なぜこのエラーが起きるのか？

1. Python 3.12以降、標準ライブラリにdistutilsが存在しない
2. 多くの古いパッケージがdistutilsに依存している
3. pip install distutilsは不可能（公式パッケージとして存在しない）

主要解決策：setuptools のインストール

distutilsの代替としてsetuptoolsをインストールすることで解決できます：

pip install setuptools

動作確認方法

インストール後、Pythonインタプリタで次のコードを実行：

# distutilsの互換性が提供されているか確認
import setuptools.dist
print("setuptoolsが正常にインポートされました")

環境別の追加対策

Homebrewユーザー（macOS）

brew install python-setuptools

Poetryユーザー

pyproject.tomlのPythonバージョンを更新：

[tool.poetry.dependencies]
python = "^3.12"  # 3.11から更新

その後依存関係を再構築：

poetry lock
poetry install

Ubuntuでのvirtualenvwrapper設定

postmkvirtualenvフックを作成：

#!/bin/bash
"${VIRTUAL_ENV}/bin/pip" install setuptools

# 元のフック機能（カスタマイズ済みの場合）
proj_name=$(basename $VIRTUAL_ENV)
mkdir -p $HOME/repos/$proj_name
add2virtualenv $HOME/repos/$proj_name

実行権限を付与：

chmod +x ~/.virtualenvs/postmkvirtualenv

シェル設定ファイル（.bashrcまたは.zshrc）に追加：

export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export VIRTUALENVWRAPPER_SETUPTOOLS=1
source /usr/share/virtualenvwrapper/virtualenvwrapper.sh

重要

新しい仮想環境を作成するたびにsetuptoolsが自動インストールされます

サードパーティパッケージ対応方法

パッケージがPython 3.12に対応していない場合：

互換性確保のための戦略

1. そのパッケージの最新バージョンを確認
2. イシュートラッカーでPython 3.12対応状況を調査
3. どうしても必要な場合はPython 3.11環境で暫定運用

最終手段：Pythonバージョンのダウングレード

どうしても問題が解決しない場合、Python 3.11以下を使用：

# Python 3.11のインストール
pyenv install 3.11.6

# ローカル環境でのバージョン設定
pyenv local 3.11.6

# 仮想環境の作成
python -m venv .venv
source .venv/bin/activate

まとめ

Python 3.12のdistutils削除問題の解決ポイント：

distutils問題の解決フロー:
Python 3.12環境で発生
     ↓
setuptoolsのインストール
     ↓
問題が解決 → 完了
     ↓
問題が残る
     ├─→ 開発環境を確認（Poetry/Homebrewなど）
     ├─→ 使用パッケージの互換性を確認
     └─→ Pythonバージョンを3.11以下にダウングレード

各解決策を段階的に試すことで、ほとんどのケースで問題は解決します。パッケージメンテナーは徐々にPython 3.12対応を進めているため、時間の経過とともにこの問題は減少していくでしょう。