現場のPythonプロジェクトで「No module named distutils.util」というエラーに遭遇し、古いライブラリのビルドが完全に止まってしまい、調査に時間を要した話です。
このエラー、実はPython 3.12以降で標準ライブラリからdistutilsが削除されたことに起因する、パッケージングシステムの進化に伴う避けられない問題でした。
何が起きたか（課題）
特定の環境でパッケージをインストールしようとしたとき、以下の症状が発生しました。
- Python 3.12環境でビルドが必要な外部ライブラリのインストールが失敗する。
- エラーログに「ModuleNotFoundError: No module named 'distutils.util'」が繰り返し現れる。
- 古い
setup.pyを持つパッケージに依存している場合に特に顕著。
どう解決したか（概要）
解決のアプローチは、一時的な対応と恒久的な対応の二段階で進めました。根本原因は、OSレベルのビルド依存性の欠如と、Python本体からのdistutilsの除去です。
まず、Linux環境で不足しているPython開発関連のパッケージをOSパッケージマネージャ経由でインストールし、ビルドに必要な依存関係を補いました。具体的には、Debian/Ubuntu系であればsudo apt install python3-distutilsを実行しました。
次に、Python 3.12以降の標準対応として、依存しているライブラリ群がsetuptoolsに依存するように移行させる必要性を確認しました。もし自分で開発しているコードであれば、from distutils.core import setupをfrom setuptools import setupに書き換える作業が必要です。また、仮想環境の再構築も行い、ホストOSの依存関係がクリーンな状態で環境が作成されるようにしました。
効果（Before/After）
OS依存パッケージのインストールとsetuptoolsのアップグレードを実施した結果、ビルドエラーは即座に解消されました。
- Before: 特定の外部パッケージのインストール試行時にビルドが失敗し、依存関係が解決しない。
- After: 依存パッケージのインストールがスムーズに完了し、Python 3.12環境での開発継続が可能になった。
🚀 詳細な設定とコードはこちら
具体的なOS別のインストールコマンド一覧や、ライブラリ開発者向けのsetup.py修正例の全文については、元のブログで詳しく解説しています。