🛠️

Python 3.12へのバージョンアップと仮想環境作成：PEP 668エラーを乗り越える

2026/01/08に公開

最新のAI（Gemini 2.5/3など）を扱うコードは、Python 3.10以降の機能をフル活用することが多いため、私の環境でもPythonを3.9から3.12へアップデートしました。
しかし、いざライブラリを入れようと pip install を実行すると、見慣れない 「PEP 668」 というエラーが発生。Geminiに聞いたところ、これは最近のMac環境で必ずと言っていいほど遭遇する「あるあるエラー」なのだそうです。

この記事では、このエラーの正体と、MacでのクリーンなPython 3.12環境の構築手順をまとめます。

 🛑 なぜ pip install で怒られるのか？（PEP 668）エラーの内容は、「OSの大事なPython環境に直接ライブラリを入れないで！壊れる可能性があるから、プロジェクトごとに専用の部屋（仮想環境）を作ってね」 という親切な警告です。
これまでのようにシステム全体にライブラリをインストールするやり方は、OSの安定性を守るために禁止されるようになりました。これからは「プロジェクトごとの仮想環境」が必須の共通ルールとなります。

 1. 🛠 Python 3.12へのバージョンアップ手順 (Mac)
 1.1. インストールHomebrewを使ってインストールします。
brew install python@3.12

 1.2. パスの設定（.zshrc）インストールしただけでは、ターミナルが新しいPythonの場所を見つけられません。設定ファイル（.zshrc）に「ここを見てね」という指示（パス）を書き込みます。
設定ファイルを開く
nano ~/.zshrc

以下の行を追記する

（libexec/bin を指定することで、python3.12 と打たなくても python だけで起動できるようになります）
export PATH="/opt/homebrew/opt/python@3.12/libexec/bin:$PATH"
保存して反映させる

Ctrl + O → Enter で保存

Ctrl + X で閉じる
以下のコマンドで設定を即座に反映
source ~/.zshrc

 1.3. 最終確認python --version
ここで Python 3.12.x と表示されれば、システム側の準備は完了です。


 2. 🛠 仮想環境（venv）の構築「個別のアプリを作るなら、自分だけの箱（仮想環境）の中でやってね」というルールに従い、プロジェクトフォルダごとに環境を作ります。

 2.1 仮想環境の作成（初回のみ）プロジェクトのルートフォルダで実行します。これにより、ライブラリを詰め込むための venv というフォルダが作成されます。
python -m venv venv

 2.2 アクティベート（作業開始のたびに実行）この「部屋」に入るためのコマンドです。実行後、ターミナルの先頭に (venv) と表示されれば成功です！
source venv/bin/activate

 2.3 ライブラリのインストールアクティベートされた状態で pip を使えば、もう PEP 668 エラーは出ません。
pip install -r requirements.txt

 💡 作業をもっと楽にする方法：VS Codeの設定毎回手動でアクティベートするのは面倒です。VS Codeの機能を活用して自動化しましょう。
事前の準備：Python拡張機能の導入
VS CodeがPythonを理解できるようにするために、Microsoft公式の「Python」拡張機能 をインストールします。拡張機能マーケットプレイスで「Python」と検索し、Microsoft製のものをインストールしてください。

操作手順：「脳みそ」をvenvに切り替える
VS Codeでプロジェクトフォルダを開く。
Cmd + Shift + P を押してコマンドパレットを開く。
「Python: インタープリターを選択 (Select Interpreter)」 を選択。
リストの中から、作成した ('venv': venv) と書かれた項目をクリック。

これで設定は完了です。以降、VS Code内で新しいターミナルを開くたびに、自動的に (venv) 状態（仮想環境がオンの状態）で始まります！

 おわりに環境構築は、開発において最もつまずきやすいポイントですが、一度「仮想環境」の文化に慣れてしまえば、依存関係のトラブルに悩まされることは格段に減ります。
最新のPython 3.12環境を整えて、AI開発を楽しみましょう！