npm install時にnpm auditのセキュリティ警告が出る場合の対処法
saratogax
サラトガ牧場
【macOS】Homebrew で Python をアップグレードしたのに反映されない？pip install も使えない？原因と解決策を徹底解説
saratogax
記事内に商品プロモーションを含む場合があります
Homebrew で Python を最新バージョンにアップグレードしたのに python3 --version が古いまま。さらに pip install しようとしたら externally-managed-environment エラー。
macOS で Python 環境を整えようとして、このような壁にぶつかった経験はありませんか？
この記事では、macOS × Homebrew 環境で Python のバージョンが切り替わらない原因と、Python 3.12 以降で pip install が使えなくなった背景、そしてそれぞれの解決策をまとめます。
Contents
この記事の対象読者
brew install python@3.13したのにバージョンが変わらなくて困っている方- macOS で Homebrew を使って Python を管理している方
pip installで externally-managed-environment エラーが出て困っている方- awscli や mkdocs などの CLI ツールを Python 環境にインストールしたい方
前提環境
- macOS（Apple Silicon / M1 以降）
- Homebrew でパッケージ管理
- シェルは zsh（macOS Catalina 以降のデフォルト）
問題1: Homebrew で Python をインストールしてもバージョンが変わらない
症状
$ brew install python@3.13
$ python3 --version
Python 3.9.6 # 変わっていない！Homebrew で新しい Python をインストールしたのに、python3 コマンドのバージョンが古いままです。
原因: keg-only と PATH の優先順位
この問題には2つの原因があります。
原因1: keg-only formula の仕組み
Homebrew の python@3.13 は keg-only な formula です。keg-only とは、Homebrew のインストール先（Cellar）にはインストールされるものの、/opt/homebrew/bin/ にシンボリックリンクが自動作成されない状態を指します。
つまり、python3 というコマンド名ではなく、python3.13 というバージョン付きの名前でしかアクセスできません。
$ ls /opt/homebrew/opt/python@3.13/bin/
idle3.13 pip3.13 pydoc3.13 python3.13 python3.13-config wheel3.13
# python3 がない！原因2: PATH の優先順位
macOS にはシステム Python が /usr/bin/python3 に存在します（3.9.6）。.zshrc で PATH の 末尾 に Homebrew のパスを追加していると、/usr/bin/python3 が先に見つかります。
# これだとシステム Python が優先される
PATH="$PATH:/opt/homebrew/opt/python@3.13/bin"解決策
ステップ1: シンボリックリンクを作成する
/opt/homebrew/bin/ に python3 と pip3 のシンボリックリンクを作成します。
ln -sf ../Cellar/python@3.13/3.13.x/bin/python3.13 /opt/homebrew/bin/python3
ln -sf ../Cellar/python@3.13/3.13.x/bin/pip3.13 /opt/homebrew/bin/pip3※ 3.13.x の部分は実際のバージョンに置き換えてください（ls /opt/homebrew/Cellar/python@3.13/ で確認できます）
ステップ2: PATH の先頭に配置する
.zshrc で /opt/homebrew/bin を PATH の先頭に追加します。
# python
PATH="/opt/homebrew/bin:$PATH"末尾ではなく先頭に追加することで、/usr/bin/python3（システム Python）より優先されます。
ステップ3: 確認
source ~/.zshrc
python3 --version
# Python 3.13.x と表示されれば成功注意: brew install で別バージョンに上書きされることがある
Homebrew で他のパッケージをインストールした際、依存関係として別バージョンの Python がインストールされ、シンボリックリンクが上書きされることがあります。
例えば brew install pipx で python@3.14 が依存としてインストールされ、/opt/homebrew/bin/python3 が 3.14 に切り替わる、ということが実際に起きます。
インストール後は python3 --version で確認する習慣をつけましょう。
問題2: pip install で externally-managed-environment エラーが出る
症状
$ pip3 install awscli
error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
xyz, where xyz is the package you are trying to install.pip install が突然使えなくなります。--user オプションを付けても同じエラーが出る場合があります。
原因: PEP 668 による保護
Python 3.12 以降、PEP 668 が導入されました。これは、OS やパッケージマネージャ（Homebrew）が管理する Python 環境に対して、pip で直接パッケージをインストールすることを制限する仕組みです。
なぜこの制限があるかというと、pip と Homebrew が同じ Python 環境に対してそれぞれパッケージを管理すると、依存関係の競合が起きて Homebrew のインストール自体が壊れる可能性があるためです。
やってはいけない解決策
以下の方法はインターネット上でよく見かけますが、推奨されません。
# Homebrew の Python 環境が壊れる可能性がある
pip3 install --break-system-packages awscli
# 保護ファイルを削除する（brew upgrade で復活する上、根本解決にならない）
sudo rm /opt/homebrew/lib/python3.13/EXTERNALLY-MANAGED正しい解決策: pipx を使う
CLI ツールのインストールには pipx を使います。pipx はツールごとに専用の仮想環境（venv）を自動作成し、コマンドだけを ~/.local/bin/ に配置してくれます。
ステップ1: pipx をインストール
brew install pipxステップ2: CLI ツールをインストール
pipx install awscli
pipx install mkdocsステップ3: PATH に ~/.local/bin を追加
.zshrc に以下を追加します（すでにある場合は不要です）
export PATH="$HOME/.local/bin:$PATH"ステップ4: 動作確認
source ~/.zshrc
aws --version
# aws-cli/x.x.x Python/3.14.x Darwin/24.x.x と表示されれば成功pipx で管理するメリット
| 項目 | pip install | pipx install |
|---|---|---|
| インストール先 | システム Python 環境 | ツール専用の venv |
| 依存関係の競合 | あり得る | 起きない |
| Homebrew との共存 | 壊れる可能性あり | 安全 |
| アンインストール | 残留ファイルが出がち | pipx uninstall で完全削除 |
補足: Homebrew の awscli から pipx に移行する場合
Homebrew 版の awscli は特定の Python バージョンに依存しています。例えば awscli が python@3.12 に依存している場合、python@3.12 をアンインストールできません。
$ brew uninstall python@3.12
Error: Refusing to uninstall python@3.12
because it is required by awscli, which is currently installed.この場合の移行手順は以下の通りです。
# 1. Homebrew 版を削除
brew uninstall awscli
# 2. pipx でインストール
pipx install awscli
# 3. 動作確認（~/.aws/config や credentials はそのまま使える）
aws --version
# 4. 不要になった Python バージョンを削除
brew uninstall python@3.12~/.aws/config や ~/.aws/credentials はファイルベースの設定なので、インストール方法を変えてもプロファイルはそのまま引き継がれます。
Python 3.12 以降のパッケージ管理の使い分け
Python 3.12 以降は、用途に応じてツールを使い分けるのが標準的な運用です。
| 用途 | 推奨ツール | 例 |
|---|---|---|
| CLI ツール | pipx | awscli, mkdocs, black, ruff |
| プロジェクトのライブラリ | venv + pip | requests, boto3, pandas |
| Homebrew にある formula | brew | （依存の Python バージョンが固定される点に注意） |
まとめ
- Homebrew の Python は keg-only なので、
python3コマンドとして使うにはシンボリックリンクの作成と PATH の優先順位設定が必要 - Python 3.12 以降は PEP 668 により、
pip installでのシステム環境へのインストールが制限される - CLI ツールは pipx で管理するのが安全で簡単。ツールごとに仮想環境が隔離される
- Homebrew 版の CLI ツール（awscli 等）は特定の Python バージョンに依存するため、pipx への移行で Python バージョンの自由度が上がる
Python のバージョン管理は年々複雑になっていますが、「Homebrew で Python 本体を管理し、CLI ツールは pipx、プロジェクトの依存は venv」という方針を持っておけば、トラブルを最小限に抑えられます。
ABOUT ME
仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。
