1. 開発開始（venv 内での動作）
- プロジェクト を venv で作成。
- venv 内では 問題なく動作。
2. venv 外での実行
- 開発したCLIアプリケーションをシステム全体で使いたくなり、venv ではなくグローバルにインストールしようと試みた。
- ところが、実際に呼ばれていたのは macOS 標準の Python 3.9 (/Users/username/Library/Python/3.9/)。
- ここで 使用ライブラリが brew の パッケージ を見つけられずエラー（OSError: no library called "package name" was found）。
- 理由: macOS 付属 Python はライブラリ検出が弱く、brew の /opt/homebrew/lib/xxx.dylib を認識できなかった。
3. Python バージョン混在の問題
- python3 --version は Homebrew 由来の 3.13 に更新されていた。
- しかし pip3 は古い 3.9 のものが PATH に残っており、python と pip のバージョンがバラバラになった。
結果:
- python3 → /opt/homebrew/bin/python3.13
- pip3 → /Users/username/Library/Python/3.9/bin/pip3
4. PEP 668「externally-managed-environment」問題
- Homebrew の Python 3.13 で正しく pip3 を使えるようになったが、今度は別の制限が発動。
- Homebrew 管理下の Python は PEP 668 に従い、pip install でシステム全体に直接パッケージを入れるのを禁止している。
- そのため pip3 install xxxxxx.whl で error: externally-managed-environment が出るようになった。
⸻
5. 解決策としての pipx
- Homebrew の Python で「アプリをグローバルに安全に使う」ために推奨されているのが pipx。
- brew install pipx → pipx install dist/xxxxxx.whl で 開発したアプリケーションをインストール。
- ただしデフォルトで ~/.local/bin に配置されるため、PATH に追加する必要があった。
- pipx ensurepath または .zshrc に export PATH="$HOME/.local/bin:$PATH" を追加して解決。
結論
- 最初: venv 内 → 問題なし。
- 次: macOS 標準 Python 3.9 → brew の cairo を認識できず失敗。
- その後: Homebrew Python 3.13 を使い始めたが、pip と python の不一致で混乱。
- さらに: PEP 668 の制限でシステムへの pip install が禁止。
- 最終解決: pipx を導入して note-thumb を安全にグローバルインストール。PATH を追加して常時利用可能に。