【Python】pyenv-virtualenv による仮想環境管理のチートシート

本記事のゴール

• pyenv-virtualenv を使用してPython仮想環境を作成・管理する
• 各種コマンドを整理

本記事は、mac OS 環境（zsh） のコマンドで説明します

1. pyenv-virtualenv の特徴

• 任意のPythonバージョンで仮想環境を作成できる
• 作成した仮想環境とPythonバージョンを一覧で確認できる
• 指定したディレクトリに移動すると自動的に仮想環境をアクティベートする機能がある

同様にPython仮想環境を作成するツールとして venv, virtualenv があるが、複数のPythonバージョンを柔軟に管理したい場合に pyenv-virtualenv が優れている

2. pyenv-virtualenv の導入

・pyenv のバージョンを確認
% pyenv --version
→ pyenv 2.6.7

・pyenv が未導入であればHomebrewでインストール
% brew install pyenv

・pyenv を最新版にアップグレード
% brew update
% brew upgrade pyenv

・pyenv virtualenv のバージョンを確認
% pyenv virtualenv --version
→ pyenv-virtualenv 1.2.4 (python -m venv)
→ pyenv: no such command `virtualenv'

・pyenv-virtualenv が未導入であればHomebrewでインストール
% brew install pyenv-virtualenv

・pyenv-virtualenv を最新版にアップグレード
% brew upgrade pyenv-virtualenv

3. pyenv-virtualenv コマンドチートシート

• 【任意のPythonバージョンを導入】

・インストール済みの Python バージョンを確認
% pyenv versions

・pyenv でインストール可能なPython一覧を表示
% pyenv install --list

・pyenv でPython 3.13.7 をインストール
pyenv install 3.13.7

---

• 【pyenvのバージョン切り替え】

① グローバル（全ターミナル共通）で切り替える場合
% pyenv global 3.13.7

② カレントディレクトリだけ切り替える場合
% pyenv local 3.13.7

③ 今のシェルセッションだけ切り替える場合
% pyenv shell 3.13.7

---

• 【pyenv-virtualenv でPython仮想環境の作成・起動・無効化・削除】

・仮想環境の作成
% pyenv virtualenv <Pythonバージョン> <環境名>
% pyenv virtualenv 3.13.7 myenv

・仮想環境を有効化
% pyenv activate myenv

・仮想環境を無効化
% pyenv deactivate

・仮想環境を削除
% pyenv uninstall myenv

・仮想環境一覧を表示（再掲）
% pyenv virtualenvs

(myenv) % pyenv virtualenvs
  3.13.7/envs/trade (created from /Users/watson/.pyenv/versions/3.13.7)
* myenv (created from /Users/watson/.pyenv/versions/3.13.7)
  trade (created from /Users/watson/.pyenv/versions/3.13.7)

---

• 【カレントディレクトリに仮想環境の自動切り替えを設定】

・自動切り替えを設定
% cd ~/myproject
% pyenv local myenv

・自動切り替え設定を削除
% cd ~/myproject
% rm .python-version

その他メモ

• 【pyenvの仮想環境の実体ファイルの場所】

・実体ファイルの場所（バージョン 3.13.7 の場合）
/Users/<ユーザー名>/.pyenv/versions/3.13.7/envs/<仮想環境名>/

・データ保管用のファイルを作成することも可能

% cd /Users/watson/.pyenv/versions/3.13.7/envs/myenv
% mkdir data

・pip でインストールしたライブラリを保管（明示的にインストールしたパッケージのみ）
(myenv) % pip list --not-required --format=freeze > requirements.txt

• 【アクティベートが上手くいかない場合の対処】

・.zshrc に適切な行を追加
% vi ~/.zshrc

eval "$(pyenv virtualenv-init -)"

・設定を反映
% source ~/.zshrc