Python仮想環境でハマった依存関係エラーの解決方法
こんにちは！今日は入れた覚えの無いパッケージが引き起こす「あるある」な謎エラーと原因について記載します。
今回の環境は Windows に Python,Anaconda を入れた状態で発生した例ですが、Linuxでも本質的には同じだとおもいます。
グローバル環境の汚染が原因だった話
問題の発生
Pythonプロジェクトの環境構築中、必要なパッケージをインストールしていたら、突然エラーメッセージが表示されました。
pip install opencv-python==4.8.1.78
実行後に表示されたエラー
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
This behaviour is the source of the following dependency conflicts.
accelerate 0.19.0 requires packaging>=20.0, which is not installed.
accelerate 0.19.0 requires psutil, which is not installed.
accelerate 0.19.0 requires torch>=1.6.0, which is not installed.
最初の疑問
「accelerateなんてインストールしてないのに...」
今回インストールしようとしていたのは、Webアプリケーション開発用のパッケージ群で、機械学習系のaccelerateは含まれていませんでした。
どこからaccelerateが出てきたのか？
原因の調査
まず、accelerateの場所を確認：
pip show accelerate
結果
Name: accelerate
Version: 0.19.0
Location: c:\users\[username]\appdata\roaming\python\python310\site-packages
Required-by:
ポイント
- Locationが仮想環境（
c:\tools\anaconda3\envs\...）ではない - ユーザーのグローバル環境（
appdata\roaming）にインストールされている Required-byが空 = 誰も依存していない
真相
ユーザー環境の全パッケージを確認
pip list --user
結果、20個以上のパッケージがグローバルに入っていることが判明。様々なプロジェクトで使われるパッケージが混在している状態でした。
原因：過去に誰か（たぶん自分💦）が仮想環境を有効化せずにパッケージをインストールしていた
よくある失敗パターン
パターン1: 仮想環境の有効化を忘れる
# 間違い：仮想環境を有効化し忘れ
pip install some-package
# 正解：仮想環境を有効化してからインストール
conda activate myenv
pip install some-package
パターン2: --userオプションの誤用
# 間違い：グローバルにインストール
pip install --user some-package
# 正解：仮想環境内にインストール
pip install some-package
パターン3: IDEの環境設定ミス
VSCodeやPyCharmで間違った環境を選択していると、意図しない場所にパッケージがインストールされる
解決方法
方法1: 問題のパッケージだけ削除
pip uninstall -y accelerate
方法2: ユーザー環境を完全クリーンアップ（これが推奨）
PowerShellで実行
pip list --user --format=freeze | ForEach-Object { $_.split('==')[0] } | ForEach-Object { pip uninstall -y $_ }
コマンドプロンプトの場合
for /f "delims==" %i in ('pip list --user --format=freeze') do pip uninstall -y %i
教訓とベストプラクティス
1. 常に仮想環境を使う
# Anaconda
conda create -n myproject python=3.10
conda activate myproject
# または venv
python -m venv myenv
myenv\Scripts\activate # Windows
source myenv/bin/activate # Linux/Mac
2. 環境の確認を習慣化
# 現在の環境を確認
where python # Windows
which python # Linux/Mac
# インストール済みパッケージの場所を確認
pip list -v
3. requirements.txtで管理
# 環境を固定
pip freeze > requirements.txt
# 再現可能な環境構築
pip install -r requirements.txt
4. ユーザー環境は空に保つ
# 定期的にチェック
pip list --user
# 理想は「空」または最小限のツールのみ
注意点：pip uninstallには--userオプションがない
多くの人が勘違いしやすいポイント
pip install --user→ ユーザー環境にインストール（存在する）pip uninstall --user→ このオプションは存在しないpip uninstall→ 自動的にユーザー環境・仮想環境の両方から探して削除
まとめ
今回のエラーは「仮想環境内のパッケージ」と「グローバル環境のパッケージ」の依存関係の衝突が原因でした。
重要なポイント
- エラーメッセージは実際には警告で、インストール自体は成功していた
- グローバル環境の汚染は、チーム開発でよくある問題
- 仮想環境を正しく使えば、このような問題は防げる
- 定期的にグローバル環境をチェックして、クリーンに保つことが重要
Python開発では仮想環境の管理が重要だということが、今回身に沁みました。
今回のような問題に遭遇したら、まずはpip showとpip list --userで環境を確認するのがよさそうです
