Pythonのバージョンを切り替える役割と、プロジェクトごとのライブラリを分離する役割は別です。pyenvでPython本体を選び、venvで依存ライブラリを分離すると、環境の違いによる不具合を切り分けやすくなります。
2026年10月8日改訂。旧記事のmacOS Catalina・Python 2を前提とした説明を更新しました。以下はmacOSのzshを想定した設定例です。
pyenvとvenvの違い
| ツール | 管理するもの | 使う場面 |
|---|---|---|
| pyenv | Python本体のバージョン | プロジェクトが要求するPythonを選ぶ |
| venv | プロジェクト内のPythonパッケージ | 別の案件や実験と依存関係を分離する |
| pip | 仮想環境内のパッケージ | ライブラリの導入・更新 |
pyenv自体は仮想環境を作成するツールではありません。この区別はpyenvの公式READMEにも記載されています。
macOSにpyenvを導入する
Homebrewを導入済みであることを前提に、ターミナルで実行します。
brew update
brew install pyenv
次の設定を~/.zshrcに追加します。PYENV_ROOTはpyenvの管理ディレクトリ、PATHはコマンドの検索先です。HOMEは既存のホームディレクトリの値をそのまま参照します。既に同じ設定がある場合は重複させません。
export PYENV_ROOT="$HOME/.pyenv"
[[ -d "$PYENV_ROOT/bin" ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"
ターミナルを開き直し、設定を確認します。Linuxやbashでは初期化方法が異なるため、公式READMEの該当するシェルの手順を参照してください。
pyenv --version
pyenv versions
プロジェクトで使うPythonを選ぶ
ここではPython 3.13系列を例にします。最新系列という意味ではなく、利用するライブラリの対応状況を確認して選ぶ例です。pyenv install 3.13は、そのpyenvが認識している3.13系列の最新版を選択します。ビルドエラーが出る場合は、公式READMEからリンクされているOS別のビルド依存関係を確認します。
pyenv install 3.13
mkdir -p python-project
cd python-project
pyenv local 3.13
python --version
pyenv version
pyenv which python
python-projectは例示用のプロジェクトディレクトリです。pyenv localで作成される.python-versionに選択したバージョンが記録されます。チームで共有する場合は、このファイルをGitで管理すると前提をそろえやすくなります。
venvでライブラリを分離する
.venvをこのプロジェクト専用の仮想環境ディレクトリとして使用します。Python標準のvenvで作成し、その環境のPythonからpipを実行します。
python -m venv .venv
source .venv/bin/activate
python -m pip --version
依存ライブラリを変更した後の記録例です。requirements.txtはインストール済みパッケージの一覧を保存するファイルです。単純な一覧はOSやPythonの違いを吸収するロックファイルではないため、再現性が重要な案件では環境条件も記録します。
python -m pip freeze > requirements.txt
deactivate
.venv自体はGitに登録せず、必要な環境で作り直します。Python本体のバージョンを変えた場合も、そのPythonで仮想環境を再作成してください。
切り替わらないときの確認点
pyenv versionsに目的のPythonが表示されるか。pyenv versionに、どの設定ファイルからバージョンが選ばれたか表示されるか。- 別のvenvが有効になっていないか。まず
deactivateで解除して確認する。 - IDEやNotebookが、ターミナルとは別のPythonを選んでいないか。
Python本体・仮想環境・IDEの実行先を分けて確認することが、環境トラブルの近道です。
