【Python】pyenvとvenvの違いと併用方法｜バージョンとライブラリを両方きれいに管理する

「pyenvとvenvって何が違うの？」「どっちを使えばいいの？」――Python開発を始めると必ずぶつかる疑問です。結論を先に言うと、この2つは役割がまったく違うツールで、併用するのが王道です。

この記事を読めば、pyenvとvenvそれぞれの役割と使い方、そして2つを組み合わせて「Pythonのバージョンも、ライブラリも、プロジェクトごとにきれいに分ける」方法が分かるようになります。

まず結論：pyenvとvenvは役割が違う

細かい話の前に、いちばん大事なところだけ押さえましょう。

pyenvはPythonのバージョンそのものを切り替えるツール、venvは選んだPythonの中でライブラリを隔離するツールです。担当している問題が別なので、片方では足りず、両方を組み合わせると最も快適になります。

【全体像】pyenvとvenvの関係

2つの関係は「入れ子」で考えると分かりやすいです。pyenvでPythonのバージョンを1つ選び、その中でvenvを使ってプロジェクトごとに箱を分けます。

同じPython 3.11を使っていても、venvで作った箱ごとにライブラリは完全に別です。Aで insightface を入れても、Bにはまったく影響しません。これが「プロジェクトごとに分離されている」状態です。

pyenv：Pythonのバージョンを管理する

pyenvは、複数のPythonバージョンをパソコンに共存させ、切り替えられるようにするツールです。「このプロジェクトは3.11、あのプロジェクトは3.12」を実現します。

インストール（macOSの例）

# Homebrewでインストール
$ brew install pyenv

# シェルの設定ファイル（.zshrc）に初期化を追記
$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
$ echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# 設定を反映（ターミナルを開き直してもOK）
$ exec $SHELL

基本の使い方

# 使いたいバージョンをインストール
$ pyenv install 3.11.9

# パソコン全体の既定バージョンを設定
$ pyenv global 3.11.9

# 特定のフォルダ（プロジェクト）だけのバージョンを設定
#   → そのフォルダに .python-version ファイルが作られる
$ cd my-project
$ pyenv local 3.11.9

# 今のバージョンを確認
$ python --version      # Python 3.11.9

# インストール済みの一覧
$ pyenv versions

pyenv local を実行すると、そのフォルダに .python-version というファイルができ、次回からそのフォルダに入るだけで自動的にそのバージョンが選ばれます。プロジェクトごとにPythonを固定できるので便利です。

venv：プロジェクトごとにライブラリを分ける

venvは、Python 3.3以降に標準で付属している仮想環境ツールです。追加インストールは不要で、Pythonが入っていればすぐ使えます。プロジェクトごとに「ライブラリの箱」を作り、その中だけにパッケージを入れることで、他のプロジェクトと混ざらないようにします。

# 仮想環境を作成（.venv という名前で作るのが一般的）
$ python -m venv .venv

# 有効化（これ以降の pip install はこの箱の中だけに入る）
$ source .venv/bin/activate      # Mac / Linux
# .venv\Scripts\activate         # Windows

# ライブラリをインストール（この環境にだけ入る）
$ pip install numpy pandas

# 依存関係をファイルに記録（共有・再現用）
$ pip freeze > requirements.txt

# 仮想環境から抜ける
$ deactivate

有効化すると、ターミナルの行頭に (.venv) のような表示が出ます。これが「今この箱の中にいる」という目印です。requirements.txt を作っておけば、別のパソコンでも pip install -r requirements.txt で同じライブラリ環境を再現できます。

pyenvとvenvを併用する（これが王道）

2つを組み合わせると、「Pythonのバージョンも、ライブラリも、プロジェクトごとに自由」という、いちばん安全で柔軟な状態になります。実際の流れはこうです。

# 1. pyenvで使いたいPythonバージョンを入れる
$ pyenv install 3.11.9

# 2. プロジェクトフォルダでバージョンを固定（.python-versionが作られる）
$ cd my-project
$ pyenv local 3.11.9
$ python --version      # Python 3.11.9 と表示されればOK

# 3. そのPythonで、プロジェクト専用のvenvを作る
$ python -m venv .venv

# 4. venvを有効化する
$ source .venv/bin/activate      # Mac / Linux
# .venv\Scripts\activate         # Windows

# 5. ライブラリをインストール（この環境にだけ入る）
$ pip install numpy pandas

# 作業を終えるとき
$ deactivate

この手順なら、pyenvがPythonのバージョンを保証し、venvがライブラリを保護してくれます。なぜ併用するのかというと、片方だけでは足りないからです。pyenvだけだと同じバージョン内でライブラリが混ざってしまい、venvだけだとPython本体のバージョンを切り替えられません。2つで役割を分担するのが正解です。

うまくいかないときの対処（トラブルシューティング）

pyenvでバージョンを変えたのに、切り替わらない

シェルの初期化（eval "$(pyenv init -)" など）が設定ファイルに入っていないのが原因です。.zshrc や .bashrc に追記し、ターミナルを開き直してください。pyenvはshims（PATHの仕組み）でバージョンを切り替えているため、この設定が必須です。

pyenv install がエラーで失敗する

pyenvはPythonをソースからビルドするため、事前にビルド用のライブラリが必要です。Macなら brew install openssl readline sqlite3 xz zlib tcl-tk を先に実行してから、再度 pyenv install を試してください。

venvを有効化したのに、pipがグローバルに入ってしまう

仮想環境の有効化（activate）を忘れているか、別のターミナルで作業している可能性があります。which python（Windowsは where python）を実行し、パスが .venv の中を指しているか確認してください。行頭に (.venv) が出ていれば有効化されています。

Windowsでactivateできない

有効化のコマンドがMacと異なります。Windowsでは .venv\Scripts\activate です。PowerShellで実行ポリシーのエラーが出る場合は、.venv\Scripts\Activate.ps1 の実行許可設定が必要になることがあります。

例えるなら「器具を選ぶ係」と「調理台を分ける係」

キッチンに例えると分かりやすいです。pyenvは「どの料理器具一式（＝Pythonのバージョン）を使うか選ぶ係」。3.11の器具、3.12の器具と選べます。venvは「その器具を使って、プロジェクトごとに別々の調理台（＝ライブラリ環境）を用意する係」。

Aの調理台、Bの調理台と分けるので、材料（ライブラリ）が混ざりません。器具を選ぶ人と調理台を分ける人――担当が違うので、両方いても役割はかぶらないのです。

まとめ

• pyenv＝Python本体のバージョンを切り替えるツール
• venv＝プロジェクトごとのライブラリを分けるツール（Python標準）
• 役割が違うので、併用するのが王道（pyenvでバージョン固定 → venvで箱を作る）
• 1つにまとめたいなら、新世代ツール uv という選択肢もある

環境を整えたら、いよいよ実際に何か作ってみましょう。たとえば「PythonでInsightFaceを使った顔認識プログラムを作る」では、ここで作った環境の上でAIの顔認識を動かせます。Pythonのバージョン管理だけをさらに詳しく知りたい方は「pyenvを使ったPythonのインストールとバージョン管理」もどうぞ。

参考リソース

• pyenv 公式GitHub（pyenv/pyenv）：インストールと使い方の一次情報
• Python公式ドキュメント「venv — 仮想環境の作成」：venvの公式リファレンス
• uv 公式ドキュメント（Astral）：新世代ツールuvの使い方