pyenvの使い方をわかりやすく解説！Pythonのバージョンを変える

Pythonを使っていると、「あれ、このプロジェクトはPython3.8じゃないと動かない」「でも他の案件では3.11を使ってる…どうしよう？」という瞬間、ありますよね。 私もエンジニア歴10年の中で、この「Pythonバージョン問題」には何度も悩まされてきました。

そんなときに出会って人生が変わったツールが pyenv（パイエンブ） です。 初めて導入したとき、「もっと早く知りたかった…！」と本気で思いました。

この記事では、IT初心者でもわかるようにpyenvの導入から使い方、トラブル解決までを徹底的にわかりやすく解説します。 実際のコマンド例や私の経験談も交えながら、どんな人でもスムーズに使えるようになることを目指します。

そもそもpyenvとは？なぜ必要なのか？¶

まず、「pyenvって何？」というところから始めましょう。 一言でいえば、Pythonのバージョンを簡単に切り替えられるツールです。

Pythonは頻繁にアップデートされ、バージョンごとに微妙な違いがあります。例えば、3.6では動いていたコードが3.11ではエラーになることもあります。そうなると、プロジェクトごとにバージョンを分けて管理する必要が出てきます。

そこで登場するのがpyenv。

pyenvを使えば、複数のPythonバージョンを共存させ、コマンド一つで切り替えられるようになります。

pyenvでできることを整理してみよう¶

実際にpyenvを導入すると、どんなことができるのか。下の表で整理してみます。

機能	内容	メリット
バージョンのインストール	さまざまなPythonバージョンを簡単に導入できる	過去のコード検証も可能
バージョン切り替え	プロジェクトごとに異なるPythonを使える	開発環境の統一が簡単
グローバル設定	デフォルトで使うPythonを指定できる	毎回設定しなくて済む
ローカル設定	フォルダ単位でPythonを固定できる	チーム開発でも混乱しない

実際に使ってみると、まるで「Pythonのバージョン管理の魔法ツール」です。 では次に、インストール方法を見ていきましょう。

pyenvのインストール方法（Mac・Linux・Windows）¶

macOSでのインストール¶

私は普段Macを使っているので、まずはMacの例から紹介します。
Macの場合、Homebrewを使えば一瞬でインストールできます。

brew update
brew install pyenv

これでpyenv本体が導入されます。 確認は次のコマンドで行います。

pyenv --version

バージョン番号が表示されればOK。 ここで何も表示されない場合は、環境変数の設定が必要です。

シェルの設定ファイル（例：~/.zshrc）に以下を追記しましょう。

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"

設定を反映させるために、ターミナルを再起動するか以下を実行します。

exec "$SHELL"

これで準備完了です。

Linuxでのインストール¶

Linuxでも手順はほぼ同じです。 パッケージマネージャーを使ってインストールするか、Gitでクローンする方法があります。

git clone https://github.com/pyenv/pyenv.git ~/.pyenv
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
source ~/.bashrc

これでLinuxでもpyenvが使えるようになります。

Windowsの場合（WSL推奨）¶

Windowsでpyenvを使う場合、WSL（Windows Subsystem for Linux）を使うのが最も安定します。 WSL上でUbuntuなどを起動し、先ほどのLinuxの手順をそのまま実行すればOKです。

もちろん、「pyenv-win」というWindows専用版もありますが、挙動が少し異なるので、私はWSLをおすすめしています。 業務でもWSL上でPythonを動かすケースが増えており、安定性も高いです。

Pythonをインストールしてみよう¶

インストールが終わったら、実際にPythonを導入してみましょう。
pyenvはインストール可能なPythonバージョンを一覧で確認できます。

pyenv install --list

ずらっと出てきます。初めて見ると驚くほど多いですが、例えばPython 3.9.13を入れたいなら、次のようにします。

pyenv install 3.9.13

これでインストール完了です。

Pythonのバージョンを切り替える方法¶

バージョンをインストールしたら、次は切り替えです。 これがpyenvの真骨頂です。

グローバルに切り替える¶

pyenv global 3.9.13

これで全体のPythonバージョンが3.9.13になります。 確認してみましょう。

python --version
# => Python 3.9.13

うまくいけば、これだけでPythonが切り替わっています。

プロジェクト単位でバージョンを固定する¶

私が特に便利だと思うのは、プロジェクトごとにPythonのバージョンを固定できる点です。 開発フォルダ内で次のように指定します。

pyenv local 3.8.10

これを実行すると、フォルダ内に.python-versionというファイルが作られます。 このフォルダに入るたびに自動的に3.8.10が使われるようになります。

複数プロジェクトを行き来している私には、本当に助かる機能です。

バージョンを削除する¶

不要になったPythonを削除するのも簡単です。

pyenv uninstall 3.8.10

これだけでスッキリ。ディスク容量の節約にもなります。

よく使うpyenvコマンドと具体的な使い方¶

pyenvにはいくつかの便利なコマンドがあります。 ただ一覧だけ見ると難しそうに感じるので、ここでは実際の使い方の流れと結果の例を一緒に紹介します。

コマンド	説明	実行例	出力例
pyenv install --list	インストール可能なPythonバージョンを表示	pyenv install --list	3.8.10, 3.9.13, 3.11.7 など
pyenv install <ver>	指定したバージョンをインストール	pyenv install 3.9.13	Downloading Python-3.9.13...
pyenv versions	現在インストール済みのバージョン一覧を表示	pyenv versions	system, 3.8.10, *3.9.13
pyenv global <ver>	全体で使うデフォルトのPythonを設定	pyenv global 3.9.13	（出力なし、設定変更）
pyenv local <ver>	現在のフォルダにだけ適用されるPythonを設定	pyenv local 3.8.10	.python-version ファイルを作成
pyenv shell <ver>	一時的にバージョンを変更（ターミナルを閉じると元に戻る）	pyenv shell 3.10.12	一時的に切り替え完了
pyenv uninstall <ver>	バージョンを削除	pyenv uninstall 3.8.10	Uninstalling Python-3.8.10...
pyenv rehash	実行キャッシュを更新	pyenv rehash	（出力なし）

コマンド使用例¶

例えば、「新しいPythonを試したいけど、今の環境は変えたくない」という場合。

pyenv install 3.10.12
pyenv shell 3.10.12
python --version
# => Python 3.10.12

このようにpyenv shellを使えば、一時的にPythonのバージョンを変更できます。 ターミナルを閉じると元の設定に戻るので、テスト用途にぴったりです。

私の失敗談：PATHの設定ミスでハマった話¶

私がpyenvを初めて使ったとき、一番ハマったのがPATHの設定ミスでした。 python --versionを実行しても、何度やっても古いPythonが表示されるんです。

原因は、システムに元々入っていたPythonが優先されていたこと。 PATHの順序を修正し、pyenvの設定を.zshrcに追記したところ、ようやく解決しました。

同じように「切り替わらない！」と悩んでいる方は、まずwhich pythonを実行して、どのPythonが使われているか確認してみてください。

which python
# /Users/username/.pyenv/shims/python

このように.pyenv/shimsが表示されれば正しく設定されています。

仮想環境との連携（pyenv + venv）¶

pyenvでPythonのバージョンを管理しつつ、仮想環境を併用するのもおすすめです。 特にvenvを使えば、ライブラリの依存関係を安全に分けられます。

pyenv local 3.10.12
python -m venv venv
source venv/bin/activate  # Mac / Linux
venv\Scripts\activate     # Windows

これでプロジェクトごとに独立したPython環境を構築できます。 チーム開発や検証作業が格段に楽になります。

pyenvのトラブルシューティング集¶

実際に使っていると、いくつかのトラブルに出くわすことがあります。 私の経験上、以下のケースが多いです。

トラブル	原因	対処法
Pythonが切り替わらない	PATHが通っていない	.zshrcの設定を再確認してexec "$SHELL"
pyenv installでエラー	ビルドツール不足	xcode-select --install や sudo apt install build-essential
pipが動かない	環境間の衝突	仮想環境を再作成して再インストール
conda環境と干渉する	PATHの順番問題	condaを無効化するか順序を調整

pyenvは便利ですが、環境変数の設定が肝心です。 一度正しく設定してしまえば、あとは快適そのものです。

エンジニア10年の私が感じるpyenvの魅力¶

私がpyenvを使い続けて感じる一番の魅力は、「環境を壊さない安心感」です。Pythonの更新や実験的なコードを試すときも、他の環境に影響を与えない。

この自由さが、開発スピードを大きく上げてくれました。

さらに、.python-versionファイルをプロジェクトに含めておけば、チーム全員が同じバージョンで動作確認できるのも大きなメリットです。

まとめ：pyenvをマスターしてPython環境を自在に操ろう¶

ここまで、pyenvのインストールから使い方、トラブル解決まで紹介してきました。 少し長く感じたかもしれませんが、一度設定してしまえば、日々の開発が驚くほど快適になります。

改めて、この記事のポイントをまとめましょう。

• pyenvはPythonバージョンを簡単に管理・切り替えできるツール
• グローバル・ローカル設定を使い分けるのがコツ
• 仮想環境と組み合わせれば最強の開発環境が作れる
• PATH設定をミスらないよう注意すること
• よく使うコマンドを覚えればトラブル知らず

最初は少し難しそうに見えても、一度触ればその便利さに驚くはずです。

ここまでお読みいただき、ありがとうございました！