🎉

Windows における pip が古い Python を参照する問題の原因と対処法

に公開
Python
pip
tech

概要

Windows 環境において python --version は新しいバージョンを示すにもかかわらず pip が古い Python を参照して失敗する事例がある . 本稿では発生要因を明確化し , 再現性のある診断手順と修復手順を提示する . 併せて再発防止策として PATH の設計指針と PowerShell による安全な呼び出し法を示す .

背景

Windows の標準インストーラは ...PythonXYZ\Scripts\pip.exe を配置する . pip.exe はランチャであり , 内部的に特定パスの python.exe と pip モジュールを呼び出す . PATH の解決順により最初に見つかった pip.exe が実行されるため , 旧バージョンの pip.exe が PATH 上位に残存すると新しい python と不整合が生じうる .

典型症状

python は 3.13 を指しているが pip 実行時に旧版のパスが表示され , ランチャが失敗する . エラーメッセージは次のような形式である .

Fatal error in launcher: Unable to create process using
"C:\Users\<USER>\AppData\Local\Programs\Python\Python311\python.exe"  "...\Python311\Scripts\pip.exe" <args>

この場合 , pip は 3.11 または 3.12 用ランチャを参照していることが分かる .

原因

原因は以下のいずれか , あるいは複合である .

  1. PATH に旧版 ...\Python311\Scripts\ などが 3.13 より前に存在する .
  2. 旧版 pip.exe が残存し , PowerShell のコマンド解決で先に選択される .
  3. PowerShell セッションのコマンドキャッシュに旧パスが残っている .

環境前提

  • OS: Windows 10/11 .
  • シェル: PowerShell 7 系 .
  • Python 3.13 が C:\Users\<USER>\AppData\Local\Programs\Python\Python313\ に存在する .

診断手順

PowerShell において以下を実行する .

# pip が実際にどのファイルに束縛されているかを確認する
Get-Command pip | Format-List *

# Windows の where を明示呼び出しして探索順を確認する
& where.exe pip

# 現在認識されている Python 群の一覧
py -0p

# 参考としてユーザー PATH とマシン PATH を確認する
'[User PATH]';   [Environment]::GetEnvironmentVariable('Path','User')   -split ';'
'[Machine PATH]';[Environment]::GetEnvironmentVariable('Path','Machine')-split ';'

Get-Command または where.exe が ...\Python311\Scripts\pip.exe や ...\Python312\Scripts\pip.exe を返す場合 , 旧ランチャが原因であると判断する .

修復手順

手順 A . 旧版 pip ランチャの除去

旧版を利用継続する場合でも pip.exe ランチャのみ除去してよい . 旧版でパッケージ操作が必要なときは py -3.12 -m pip のように起動する .

# 例: 3.12 と 3.11 と 3.8 のランチャを除去する
Remove-Item "$env:LOCALAPPDATA\Programs\Python\Python312\Scripts\pip*.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\Python\Python311\Scripts\pip*.exe" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:LOCALAPPDATA\Programs\Python\Python38\Scripts\pip*.exe"  -Force -ErrorAction SilentlyContinue

# 残存確認
Get-ChildItem -Path "$env:LOCALAPPDATA\Programs\Python" -Recurse -Filter "pip*.exe" -ErrorAction SilentlyContinue |
  Select-Object FullName

手順 B . 3.13 の pip を再生成し , 最新化する

py -3.13 -m ensurepip --upgrade
py -3.13 -m pip install --upgrade pip

手順 C . 新しい PowerShell セッションで検証する

PowerShell をいったん全て閉じ , 新しいセッションを開いて確認する .

& where.exe pip
Get-Command pip
pip --version
pip list

where と Get-Command の出力が ...\Python313\Scripts\pip.exe を指し , pip --version が python 3.13 を示せば修復完了である .

再発防止策

1) PATH の設計指針

ユーザー PATH において以下の 2 行を上位に配置する .

C:\Users\<USER>\AppData\Local\Programs\Python\Python313\Scripts\
C:\Users\<USER>\AppData\Local\Programs\Python\Python313\

旧版の ...\PythonXYZ\Scripts\ と ...\PythonXYZ\ が存在する場合は 3.13 より後方に配置するか削除する . システム PATH 側にも旧版が無いかを確認する .

2) PowerShell 関数による安全なラップ

環境が未整備の間は pip を常に現在の python に結びつける関数を用いると安全である .

# セッション限定
function pip { python -m pip @Args }

# 恒久化する場合
notepad $PROFILE
# 上記ファイル末尾に  function pip { python -m pip @Args }  を 1 行追記して保存する

3) バージョン共存時の原則

複数系統を共存させる場合 , pip 単独呼び出しは避け , 常に明示的に指定する .

py -3.13 -m pip install <package>
py -3.12 -m pip install <package>

まとめ

本稿は Windows において pip が旧版 Python を参照する問題の原因を pip.exe ランチャの残存と PATH 解決順の不整合に求め , 診断から修復までの一貫した手順を示した . 旧ランチャの除去 , 新版 pip の再生成 , PATH 設計の見直しにより問題は解消する . 併せて python -m pip の運用を採用することで , 複数系統共存時でも安全性と可搬性を確保できる .

Discussion