Pythonで開発をしていると、「このプロジェクトは3.12、別のプロジェクトは3.10じゃないと動かない！」というバージョン衝突の問題に直面します。この「バージョン地獄」を解決し、PC一台で複数のPython環境を自在に切り替えられるようにするのが、pyenvです。
この記事では、Mac/LinuxユーザーとWindowsユーザー、両方に対応したpyenvの導入方法から、現場で役立つ基本コマンドまでを徹底解説します。
🚀 導入編：pyenvをセットアップする
環境によって導入ツールが異なりますが、やることはシンプルです。
Mac / Linux ユーザー (pyenv)
pyenv本体のインストール
パッケージマネージャーのHomebrew（Mac）またはGitを使ってインストールします。
# Mac (Homebrew推奨)
$ brew install pyenv
# Linux（GitHubからpyenvリポジトリをホームディレクトリの隠しフォルダにクローン）
$ git clone https://github.com/pyenv/pyenv.git ~/.pyenv
環境変数（パス）の設定
pyenvがPythonのバージョンをフックできるように、シェルの設定ファイル（.zshrcや.bashrc）の末尾に以下の設定を追記します。
# .zshrc や .bashrc に追記
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
# 💡 設定ファイル保存後、ターミナルを再起動するか、
# source ~/.zshrc で設定を反映させることを忘れずに！
Windows ユーザー (pyenv-win)
Windowsでは、コミュニティが開発したpyenv-winというツールを使用します。
pyenv-win のインストール
PowerShellを使ってインストールするのが簡単です。
git clone https://github.com/pyenv-win/pyenv-win.git "$env:USERPROFILE\.pyenv"
設定の反映
インストールが完了したら、PowerShellを一度閉じ、再度立ち上げ直します。これでpyenvコマンドが使えるようになります。
# pyenvのバージョンを確認
pyenv --version
🛠️ コマンド編：これだけ覚えればOKな基本操作
Mac/Linux版とWindows版（pyenv-win）で、利用するコマンドは共通です。
| コマンド | 目的 | 例 |
|---|---|---|
| pyenv install -l | インストール可能な全バージョンを一覧表示します。 | $ pyenv install -l |
| pyenv install [ver] | 指定したPythonのバージョンをインストールします。 | $ pyenv install 3.11.8 |
| pyenv versions | インストール済みの全バージョンと、現在適用中のバージョンを確認します。 | $ pyenv versions |
| pyenv global [ver] | システム全体で使用するPythonバージョンを設定します（デフォルト）。 | $ pyenv global 3.12.3 |
| pyenv local [ver] | 現在のディレクトリとその配下でのみ使用するバージョンを設定します。 | $ pyenv local 3.10.13 |
| pyenv local --unset | 現在のディレクトリのローカル設定を解除します。 | $ pyenv local --unset |
| pyenv uninstall [ver] | 不要になったバージョンをアンインストールします。 | $ pyenv uninstall 3.8.10 |
| pyenv rehash | (Mac/Linuxのみ) 新しいバージョンやパッケージをインストールした際、必ず実行してください。（Windows版では通常不要です） | $ pyenv rehash |
💡 応用編：プロジェクトごとのバージョン切り替えフロー
pyenvの最も強力な機能は、プロジェクトフォルダに入ったときだけ、自動でバージョンが切り替わることです。
プロジェクトフォルダを作成・移動
$ mkdir my-latest-project && cd my-latest-project
必要なバージョンをインストール
$ pyenv install 3.11.8
フォルダのバージョンを設定
対象のフォルダ上でpyenv localを実行すると、対象フォルダ内に.python-versionというファイルが作成されます。
$ pyenv local 3.11.8
バージョン確認
pythonコマンドを実行するだけで、設定したバージョンが使われていることを確認できます。
$ python --version
# Python 3.11.8 と表示される
これで、プロジェクト間を移動するだけで、Pythonバージョンが自動で切り替わる開発環境が整いました！
最後に
pyenvは、Python開発における環境トラブルを劇的に減らしてくれる、まさに「縁の下の力持ち」です。この備忘録が、あなたの快適なPythonライフに役立てば幸いです。
ぜひ、プロジェクトごとにpyenv localを設定する習慣をつけてみてください！