できない.dev

pip をアップグレードできない(pip install --upgrade pip が失敗する)

Windows では pip.exe が自分自身を上書きできず Access is denied で失敗するのが定番。
python -m pip install --upgrade pip と python -m 経由で実行する。
権限エラーや PEP 668 の拒否は venv 内で行うのが基本。

公開: 更新:

要約

pip install --upgrade pip が失敗する典型は Windows で、ERROR: To modify pip, please run the following command: python -m pip install --upgrade pip や Access is denied が出る。
pip.exe 経由の実行では、起動中の自分自身を上書きできない ためで、python -m pip install --upgrade pip と python -m 経由で実行する のが正しい手順である。
Unix 系の権限エラーや PEP 668 による拒否は、システム Python を直接触らず venv 内で行うことで解決する。

解決策

1. python -m 経由で実行する

python -m pip install --upgrade pip
# Windows の py ランチャー利用時
py -m pip install --upgrade pip

この形なら pip.exe 自体は起動せず、モジュールとして実行されるため自分自身の上書き問題が起きない。
公式ドキュメントの Upgrading pip(新しいタブで開く) もこの手順を案内している。

2. venv 内でアップグレードする

python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip

venv 内なら権限エラーも PEP 668 の拒否も発生しない。
プロジェクト作業用の pip はシステムではなく venv 側を新しくすれば十分なことが多い。

3. ユーザー環境に入れる

python -m pip install --upgrade --user pip

venv を使わない場合は --user でユーザーディレクトリ側にインストールできる。
ただし PATH の優先順位によっては古い方が呼ばれ続けるため、python -m pip --version でどちらが使われているかを確認する。

4. ネットワーク設定を見直す

プロキシ環境では --proxy オプションや環境変数(HTTPS_PROXY)を設定する。
SSL エラーで失敗する場合は証明書設定の問題であり、アップグレード以前に pip 全体の通信が失敗しているので、そちらを先に解決する。

よくある原因

  1. Windows で pip が自分自身を上書きしようとしている。
    pip.exe の実行中はそのファイルがロックされ、置き換えできない。
  2. 書き込み権限が無い。
    システム Python の site-packages を変更するには、管理者権限が要る。
  3. Python が externally-managed-environment になっている。
    OS 管理の Python(Debian / Ubuntu / Homebrew など)は、PEP 668 に従ってシステム環境の変更を拒否する。
  4. ネットワークで止まっている。
    プロキシ環境や SSL 検査により、PyPI への接続が失敗している。