Pythonのエポックミリ秒入門｜取得・変換コードと注意点
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 コマンドのバージョンが古いままです。
原因: 無印の python3 の在り処と PATH の優先順位
この問題には2つの原因があります。
原因1: 無印の python3 は libexec/bin に置かれる
Homebrew が /opt/homebrew/bin/ に python3 という無印の名前を置くのは、「デフォルトの python3」に選ばれている 1 つのバージョンだけです。それ以外のバージョンには、python3.13 のようなバージョン付きの名前しか置かれません。
どのバージョンがデフォルトかは Homebrew 側の都合で決まり、時期によって変わります（この記事の更新時点では python@3.14 が python3 の実体です）。python@3.13 はデフォルトではないので、python3 という名前は付きません。
※「python@3.13 は keg-only だから」と説明されることがありますが、これは誤りです。keg-only なら python3.13 すら PATH に出ませんが、実際には出ます（brew info python@3.13 で確認できます）。
$ ls /opt/homebrew/opt/python@3.13/bin/
idle3.13 pip3.13 pydoc3.13 python3.13 python3.13-config wheel3.13
# python3 がない！では無印の python3 はどこにあるかというと、同じ formula の libexec/bin の下にまとめて置かれています。python / python3 / pip / pip3 といった無印・メジャー版の名前はすべてこちら側です。ここは PATH に入っていないため、そのままでは使えません。
原因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: python3 の実体を PATH に通す
方法は 2 つあります。バージョンにこだわりがなければ方法A、特定のバージョンを使い続けたいなら方法Bを選びます。
方法A: デフォルトの python3 を入れる。python3 という formula を入れると、その時点のデフォルトバージョンが /opt/homebrew/bin/python3 として置かれます。リンクを張るのは Homebrew 自身なので、あとから壊れません。
brew install python3方法B: バージョンを固定する。python@3.13 を使い続けたい場合は、先ほどの libexec/bin を PATH に通します。無印の python / pip もこれで使えるようになります。
# .zshrc
PATH="$(brew --prefix python@3.13)/libexec/bin:$PATH"brew --prefix を使えば、バージョン番号を自分で書かずに済みます。
ステップ2: PATH の先頭に配置する
方法A の場合、.zshrc で /opt/homebrew/bin を PATH の先頭に追加します（方法Bは上の 1 行で先頭に入るため不要です）。
# python
PATH="/opt/homebrew/bin:$PATH"末尾ではなく先頭に追加することで、/usr/bin/python3（システム Python）より優先されます。
ステップ3: 確認
source ~/.zshrc
python3 --version
# 方法Aなら 3.14.x、方法Bなら 3.13.x と表示されれば成功アンチパターン: 手動でシンボリックリンクを張らない
検索すると、/opt/homebrew/bin/python3 に ln -sf で直接シンボリックリンクを張る方法も出てきます。その場は動きますが、Homebrew が管理している場所を手で書き換えることになるため、おすすめしません。
# その場は動くが、Homebrew に黙って上書きされる
ln -sf ../Cellar/python@3.13/3.13.x/bin/python3.13 /opt/homebrew/bin/python3実際、brew install pipx をすると依存として python@3.14（＝デフォルトの python3）が入り、/opt/homebrew/bin/python3 は Homebrew 自身の手で 3.14 に張り替えられます。手動リンクはここで消えます。バージョンが勝手に戻ったように見える正体はこれです。
方法A・方法Bなら、この上書きは起きません。方法Aは Homebrew が張ったリンクをそのまま使い、方法Bは Homebrew が触らない PATH 設定だけで解決しているためです。
問題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 バージョンが固定される点に注意） |
まとめ
- 無印の
python3が付くのはデフォルトの 1 バージョンだけ。それ以外を使うならbrew install python3か、libexec/binを PATH に通す（手動リンクは Homebrew に上書きされる） - Python 3.12 以降は PEP 668 により、
pip installでのシステム環境へのインストールが制限される - CLI ツールは pipx で管理するのが安全で簡単。ツールごとに仮想環境が隔離される
- Homebrew 版の CLI ツール（awscli 等）は特定の Python バージョンに依存するため、pipx への移行で Python バージョンの自由度が上がる
Python のバージョン管理は年々複雑になっていますが、「Homebrew で Python 本体を管理し、CLI ツールは pipx、プロジェクトの依存は venv」という方針を持っておけば、トラブルを最小限に抑えられます。
pip 自体の基本的なコマンド操作（list / install / freeze / アップグレードなど）は、こちらの記事に一覧でまとめています。
あわせて読みたい
pipのコマンド操作とオプション一覧
ABOUT ME
仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。
