【完全ガイド】pyenvとは？複数のPythonバージョンを簡単に切り替える最強ツールの使い方

Pythonを使っていて、こんな経験ありませんか？

古いプロジェクトはPython 3.6、新しいのは3.12で動かしたい
他の人の環境と合わせる必要があるけど、どうやって？
システムのPythonを書き換えるのは怖い…

そんな悩みをすべて解決してくれるのが、「pyenv（パイエンブ）」です。

この記事では、pyenvの基本からインストール手順、使い方、そしてよくあるエラーへの対処法まで、初心者にもすぐ実践できる形で丁寧に解説します。

pyenvとは何か？簡単に言うと…
pyenvのインストール手順（Mac/Linux向け）
pyenvの基本的な使い方【実践編】
pyenvとvenv（仮想環境）の連携【実務で必須】
pyenvのよくあるエラーと対処法
まとめ：pyenvはPython開発の必須ツール！

pyenvとは何か？簡単に言うと…

pyenvの役割

pyenvは、複数のPythonバージョンを簡単にインストール・切り替えできるツールです。

開発環境ごとに異なるバージョンのPythonを使いたいとき、システムに影響を与えずに自由に管理できるのが最大のメリットです。

pyenvでできること

任意のPythonバージョンを簡単にインストール
プロジェクトごとにPythonバージョンを指定
システムのPythonを汚さずに新旧共存

なぜpyenvが必要なの？

例：こんな状況を想像してみてください

あなたのパソコンにはPython 3.8がインストールされています。でも：

会社のプロジェクトA：Python 3.9で作られている
個人のプロジェクトB：Python 3.12の新機能を使いたい
古いプロジェクトC：Python 3.7でないと動かない

pyenvがあれば、これらすべてを同じパソコンで問題なく使い分けできます！

まとめ

pyenvは、Pythonバージョン問題を完全に解決する必須ツールです。次の章ではインストール手順を詳しく見ていきましょう。

pyenvのインストール手順（Mac/Linux向け）

事前準備（必要なソフトウェアをインストール）

Pythonをビルド（コンパイル）するために、いくつかのソフトウェアが必要です。

Debian/Ubuntu系（WSL含む）の場合：

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl \
llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev

Mac（Homebrew使用）の場合：

brew install openssl readline sqlite3 xz zlib

pyenvのインストール

公式のインストールスクリプトを使用します：

curl https://pyenv.run | bash

このコマンドは：

pyenvの本体をダウンロード
必要なファイルを適切な場所に配置
関連ツールも一緒にインストール

シェル設定の追加

pyenvを使えるようにするため、シェルの設定ファイルに追記します。

bashを使っている場合（~/.bashrcに追記）：

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

zshを使っている場合（~/.zshrcに追記）：

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

設定を反映

設定ファイルを編集したら、以下のコマンドで反映します：

source ~/.bashrc  # bashの場合
# または
source ~/.zshrc   # zshの場合

インストールが成功したか確認

pyenv --version

バージョン番号が表示されれば、インストール成功です！

まとめ

pyenvのインストールは一度だけでOK。シェル設定ができれば、すぐ使い始められます。

pyenvの基本的な使い方【実践編】

インストール可能なバージョンを確認

どのPythonバージョンがインストールできるか確認してみましょう：

pyenv install --list

たくさんのバージョンが表示されます。最新版を選ぶか、プロジェクトで指定されたバージョンを選びましょう。

任意のPythonバージョンをインストール

例えば、Python 3.10.12をインストールする場合：

pyenv install 3.10.12

インストールには少し時間がかかります（5〜15分程度）。コーヒーでも飲んで待ちましょう！

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

pyenvでは、3つの方法でPythonバージョンを切り替えられます。

1. 一時的に切り替える（現在のターミナルだけ）

pyenv shell 3.10.12

このターミナルを閉じるまで、Python 3.10.12が使われます。

2. グローバル（全体）で使うバージョンを指定

pyenv global 3.12.0

パソコン全体のデフォルトPythonを変更します。最初に設定する時におすすめ。

3. ディレクトリごとに指定（プロジェクトごと）

cd my-project
pyenv local 3.9.0

このディレクトリに入ると、自動的にPython 3.9.0が使われます。.python-versionというファイルが作成され、バージョン情報が保存されます。

今どのバージョンが使われているか確認

pyenv version

現在使用中のPythonバージョンが表示されます。

インストール済みのバージョン一覧

pyenv versions

インストール済みのすべてのPythonバージョンが表示されます。現在使用中のものには*マークが付きます。

まとめ

プロジェクトごとにバージョンを変えたいときは、pyenv localが超便利！次の章では仮想環境との連携も紹介します。

pyenvとvenv（仮想環境）の連携【実務で必須】

なぜ仮想環境が必要？

例：ライブラリのバージョン問題

プロジェクトA：Django 3.2を使用
プロジェクトB：Django 4.2を使用

同じPythonバージョンでも、ライブラリのバージョンが違うと問題が起きます。仮想環境を使えば、プロジェクトごとに独立したライブラリ環境を作れます。

pyenvでPythonを選んでから仮想環境を作る

# 1. プロジェクト用のPythonバージョンを選ぶ
pyenv shell 3.10.12

# 2. 仮想環境を作る
python -m venv venv

# 3. 仮想環境を有効にする
source venv/bin/activate  # Mac/Linux
# venv\Scripts\activate   # Windows

# 4. 必要なライブラリをインストール
pip install django==4.2

この方法なら、pyenvで選んだバージョンを使って仮想環境を作れる！

より便利な方法：pyenv-virtualenv

pyenvにはpyenv-virtualenvという拡張機能があります：

# Python 3.10.12を使って「myproject」という名前の仮想環境を作る
pyenv virtualenv 3.10.12 myproject

# 仮想環境を有効にする
pyenv activate myproject

# 仮想環境を無効にする
pyenv deactivate

自動化のアイデア

direnvとの組み合わせ direnvというツールを使えば、ディレクトリに入るだけで自動的に環境を切り替えられます：

# .envrcファイルを作成
echo "pyenv activate myproject" > .envrc
direnv allow

実際の開発フローの例

# 1. プロジェクトディレクトリを作成
mkdir my-django-app
cd my-django-app

# 2. このプロジェクト用のPythonバージョンを設定
pyenv local 3.10.12

# 3. 仮想環境を作成・有効化
python -m venv venv
source venv/bin/activate

# 4. 必要なライブラリをインストール
pip install django
pip freeze > requirements.txt

# 5. 開発開始！
django-admin startproject mysite .

まとめ

pyenv + venvで、プロジェクトごとに独立した環境を安全に作れるようになります。これで「他の人の環境で動かない」問題ともさよならです！

pyenvのよくあるエラーと対処法

Pythonのビルドに失敗する

エラー例：

ERROR: The Python ssl module is not available.
BUILD FAILED (Ubuntu 20.04 using python-build 20180424)

原因： 必要なライブラリが不足している

対処法： 依存パッケージを再度インストール

# Ubuntu/Debian系
sudo apt install -y libssl-dev

# Mac
brew install openssl

# インストール後、Pythonを再ビルド
pyenv install 3.10.12

pyenvが反映されない

症状： pyenv globalで設定しても、システムのPythonが使われる

対処法： シェル設定が正しく読み込まれているか確認

# PATHにpyenvが含まれているか確認
echo $PATH

# pyenvコマンドが認識されているか確認
type pyenv

# 設定ファイルを再読み込み
source ~/.bashrc  # または ~/.zshrc

特定のバージョンがインストールできない

エラー例：

python-build: definition not found: 3.11.5

対処法： pyenvを最新バージョンに更新

# pyenvを更新
cd ~/.pyenv
git pull

# 再度インストールを試行
pyenv install 3.11.5

M1/M2 Macでビルドが失敗する

症状： Apple Silicon MacでPythonのビルドがうまくいかない

対処法： 特別な環境変数を設定

# M1/M2 Mac専用の設定
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CPPFLAGS="-I$(brew --prefix openssl)/include"

# Pythonをインストール
pyenv install 3.10.12

Windowsでは使えないの？

pyenv自体はWindowsに直接は非対応ですが、以下の方法で代用できます：

1. WSL（Windows Subsystem for Linux）を使用

# WSLをインストール後、Linux環境でpyenvを使用
curl https://pyenv.run | bash

2. pyenv-winを使用

# PowerShellで実行
git clone https://github.com/pyenv-win/pyenv-win.git %USERPROFILE%\.pyenv

権限エラーが出る

エラー例：

Permission denied

対処法： sudoを使わずに実行。pyenvはユーザー権限で動作します。

# ❌ 間違った方法
sudo pyenv install 3.10.12

# ✅ 正しい方法
pyenv install 3.10.12

まとめ

エラーが出ても落ち着いて。メッセージを読めば大抵の問題は解決できます！ 分からないときは、エラーメッセージをそのままGoogle検索するのも有効です。

まとめ：pyenvはPython開発の必須ツール！

pyenvの重要ポイント

pyenvは複数バージョンのPythonを安全かつ簡単に切り替えられるツール
pyenv install、pyenv global、pyenv local の3つのコマンドを覚えよう
仮想環境と組み合わせれば、プロジェクトごとの環境構築が超快適
WindowsでもWSLやpyenv-winを使えば導入可能！

こんな人におすすめ

複数のPythonプロジェクトを管理している人
チーム開発で環境を合わせる必要がある人
新しいPythonバージョンを試したい人
システムのPythonを汚したくない人

実際の開発での使い方

# 新しいプロジェクトを始める時の手順
mkdir new-project
cd new-project
pyenv local 3.11.5        # プロジェクト用バージョンを設定
python -m venv venv        # 仮想環境を作成
source venv/bin/activate   # 仮想環境を有効化
pip install -r requirements.txt  # 必要なライブラリをインストール