閉じる

これで迷わないpyenvの使い方(インストール/設定/実例)

プロジェクトごとにPythonのバージョンが違っていて困った経験はありませんか。

OSに入っているPythonとpipをそのまま使うと、別プロジェクトで必要なバージョンと衝突しがちです。

pyenvを使えば、各プロジェクトで必要なPythonをインストールし、シンプルなコマンドで切り替えられます。

この記事ではインストールから設定、実例まで初心者向けに丁寧に解説します。

目次 [ close ]
  1. pyenvとは？Pythonのバージョンをプロジェクトごとに切り替え
    1. 初心者向けpyenvの使い方(できること)
    2. なぜ必要か(Pythonバージョン管理の理由)
    3. 仕組みの超概要(shimsで切り替え)
  2. pyenvのインストール(Mac/Linux/Windows)
    1. Macでのインストール(Homebrew)
    2. Linux(Ubuntu系)でのインストール
    3. Windowsはpyenv-winを使う
    4. インストール前の準備(必要パッケージ)
  3. 初期設定と基本コマンド(設定/確認/切り替え)
    1. シェルに初期化を追加(zsh/bash)
    2. Pythonの追加(pyenv install)
    3. バージョン一覧の確認(pyenv versions)
    4. デフォルトを設定(pyenv global)
    5. プロジェクトだけ切り替え(pyenv local)
    6. 一時的に切り替え(pyenv shell)
    7. .python-versionの役割
  4. 実例: プロジェクトごとにPythonを固定する手順
    1. 1. プロジェクト作成と移動
    2. 2. 必要なPythonをインストール(例: 3.12系)
    3. 3. プロジェクトに紐づけ(pyenv local 3.12.x)
    4. 4. バージョン確認(python -V)
    5. VSCodeでインタプリタを選ぶ(Interpreter選択)
    6. よくあるつまずき(PATHが反映されない/シェル再起動)
  5. まとめ

pyenvとは？Pythonのバージョンをプロジェクトごとに切り替え

pyenvは、複数のPythonバージョンをユーザー権限で共存させ、global・local・shellといったスコープで瞬時に切り替えるツールです。

システムPythonを汚さずに、必要なバージョンだけ安全に追加・選択できるのが大きな魅力です。

初心者向けpyenvの使い方(できること)

大まかには次のことができます。

文章で理解してから実践に進むと迷いません。

  • 必要なPythonのバージョンをインストールします。指定できるのは3.12系や3.11系など、多数の公式リリースです。複数バージョンを同時に保持可能です。
  • デフォルトのPythonを設定します。これは全体の既定値です。
  • プロジェクトフォルダ単位でPythonを指定します。そのフォルダに入ったときだけ自動で切り替わります。
  • 一時的にカレントシェルだけ別バージョンに切り替えることもできます。
注意

pyenvはPython本体の「版」管理です。

パッケージの隔離は仮想環境(venv)の役目です。

両者は補完関係にあります。

なぜ必要か(Pythonバージョン管理の理由)

Pythonはバージョンごとに文法や標準ライブラリ、依存するOSライブラリの条件が異なります。

例えば、Aプロジェクトは3.12、Bプロジェクトは3.10を要求する、といった状況は珍しくありません。

pyenvがあれば、OSにプリインストールされたPythonをいじらずに、プロジェクトごとに適切なバージョンを選べます。

これは再現性の担保や、EOL(サポート期限)の管理にも有効です。

さらに、pyenvで選んだPythonの上にvenvを作ることで、プロジェクト内のライブラリも衝突せずに保てます。

仕組みの超概要(shimsで切り替え)

pyenvはshimsという薄いラッパー実行ファイル群を~/.pyenv/shimsに用意し、PATHの先頭に置く仕組みを使います。

ユーザーがpythonやpipを実行すると、まずshimが呼ばれ、現在のコンテキストに合わせた実体のPythonへ委譲します。

このときの優先順位は「shell指定」>「local指定」>「global指定」です。

例としてPATHの先頭にshimsがある状態をテキスト図で示します。

  • PATH: ~/.pyenv/shims:/usr/local/bin:/usr/bin
  • 実行: python → ~/.pyenv/shims/python → 選択されたバージョンの.../versions/X.Y.Z/bin/python

この仕組みのおかげで、フォルダを移動するだけでバージョンが自動で切り替わります。

pyenvのインストール(Mac/Linux/Windows)

環境により最適な導入方法が異なります。

ここでは一般的かつ再現しやすい手順をまとめます。

インストール前にビルドに必要なパッケージを整えると失敗が減ります。

Macでのインストール(Homebrew)

Homebrewを使うのが簡単です。

まずXcodeのコマンドラインツールを入れてからpyenvを導入します。

Shell
# 1) Xcode Command Line Tools を入れる(未導入の場合)
xcode-select --install

# 2) Homebrew が未インストールならインストール(省略可)
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 3) pyenv をインストール
brew update
brew install pyenv

# 4) よく使うSSL等のライブラリも入れておくとビルドが安定します
brew install openssl readline sqlite3 xz zlib tcl-tk

実行後、シェル初期化が必要です。

zshを例に示します。

Shell
# zsh の初期化ファイルに追記
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(pyenv init -)"' >> ~/.zshrc

# ログインシェル用に PATH を早期設定(zsh の場合は .zprofile に)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile

最後にシェルを再読み込みします。

Shell
# 設定を有効化
exec $SHELL -l

# バージョン表示で確認
pyenv --version
実行結果
pyenv 2.4.0

Homebrew経由の場合でもPYENV_ROOTとPATHの設定は有効です。

macOSでは/opt/homebrew系のパス調整が必要な場合があります。

Linux(Ubuntu系)でのインストール

Ubuntuでは、必要ライブラリの準備→Gitでpyenvをクローン→シェル初期化の流れが確実です。

Shell
# 1) 依存パッケージ(ビルドツールや各種ライブラリ)を導入
sudo apt update
sudo apt install -y \
  build-essential curl git ca-certificates \
  libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
  libsqlite3-dev libffi-dev libncursesw5-dev \
  liblzma-dev tk-dev uuid-dev xz-utils

# 2) pyenv をクローン
git clone https://github.com/pyenv/pyenv.git ~/.pyenv

# 3) シェル初期化に追記
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# 4) 設定を反映
exec $SHELL -l

# 5) 動作確認
pyenv --version
実行結果
pyenv 2.4.0

ビルド依存が不足するとpyenv installで失敗します。

上記を満たしてからインストールしましょう。

Windowsはpyenv-winを使う

Windowsでは本家pyenvの代わりにpyenv-winを利用します。

コマンド体系はほぼ同じで、PowerShellやcmdから使用できます。

主なインストール方法は次の通りです。

  • Chocolateyを使う方法
PowerShell
# 管理者権限のPowerShell
choco install pyenv-win -y
  • Scoopを使う方法
PowerShell
# 一般ユーザーのPowerShell
scoop install pyenv
  • wingetを使う場合はまず検索してIDを確認します
PowerShell
winget search pyenv-win
# 表示されたIDを使って
# winget install <表示されたID>

インストール後、%USERPROFILE%.pyenv\pyenv-win\binと%USERPROFILE%.pyenv\pyenv-win\shimsがPATHに含まれていることを確認し、新しいターミナルを開き直してください。

PowerShell
pyenv --version
実行結果
pyenv 2.64.11
注意

WSL(Windows Subsystem for Linux)内でLinux版pyenvを使うことも可能ですが、Windowsのpyenv-winとは別物です。

混同しないようにしてください。

インストール前の準備(必要パッケージ)

PythonのビルドにはOSごとの開発用ライブラリが必要です。

足りないとビルドに失敗します。

  • macOSでよく必要になるもの
    • Xcode Command Line Tools
    • Homebrew経由でopenssl、readline、sqlite3、xz、zlib、tcl-tkなど
    • 場合によっては次のフラグが役立ちます
Shell
# Homebrewのライブラリを優先する例
export LDFLAGS="-L$(brew --prefix openssl)/lib -L$(brew --prefix readline)/lib"
export CPPFLAGS="-I$(brew --prefix openssl)/include -I$(brew --prefix readline)/include"
  • Ubuntu系で必要になるもの
    • 先述のlibssl-devやzlib1g-devなどの開発パッケージ一式

まず依存関係を整え、それからpyenv installに進むのが成功率を高めます。

初期設定と基本コマンド(設定/確認/切り替え)

ここからは実際に動かす流れを段階的に説明します。

最初に「シェル初期化」→「Python追加」→「切り替え」の順で覚えると理解がスムーズです。

シェルに初期化を追加(zsh/bash)

pyenvのshimsが優先されるよう、シェルの設定ファイルに初期化を追記します。

zshの例は次の通りです。

Shell
# ~/.zshrc に追記
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

bashの場合は~/.bashrcに同様の内容を入れます。

反映はexec $SHELL -lが手軽です。

Shell
# 反映と確認
exec $SHELL -l
which python
実行結果
/home/you/.pyenv/shims/python

shimsが先に来ていれば初期化成功です。

Pythonの追加(pyenv install)

欲しいバージョンをインストールします。

候補は一覧から確認できます。

Shell
# 候補リスト(抜粋が大量に表示されます)
pyenv install -l | sed -n '1,40p'  # 最初の40行だけ例として表示

# 例: 3.12系の最新パッチを入れる
pyenv install 3.12.6

# 進捗が止まったように見える時は詳細表示で
pyenv install -v 3.12.6

出力例(一部):

実行結果
Downloading Python-3.12.6.tar.xz...
Installing Python-3.12.6...
Installed Python-3.12.6 to /home/you/.pyenv/versions/3.12.6

ビルドに失敗したら、依存パッケージの不足や古いOpenSSLが原因のことが多いです。

前章の準備を見直してください。

Windows(pyenv-win)では、基本的にプリビルドを取得するため、Linuxのようなビルドエラーは発生しにくいです。

バージョン一覧の確認(pyenv versions)

インストール済みのバージョンと選択状態を確認します。

Shell
pyenv versions
実行結果
  system
  3.10.14
* 3.12.6 (set by /home/you/.pyenv/version)

先頭の*は現在選ばれているバージョンを示します。

systemはOSのPythonです。

デフォルトを設定(pyenv global)

全体の既定バージョンを設定します。

迷ったら最新安定版を指定しておくと便利です。

Shell
pyenv global 3.12.6
python -V
実行結果
Python 3.12.6

globalは全体の基準値で、後述のlocalやshellがなければこれが使われます。

プロジェクトだけ切り替え(pyenv local)

特定フォルダ内だけバージョンを変えたいときはlocalを使います。

そのフォルダに.python-versionファイルが作られ、以降自動で適用されます。

Shell
# 例: あるプロジェクトで3.10系を使いたい
cd /path/to/project
pyenv local 3.10.14

# 確認
python -V
実行結果
Python 3.10.14

一時的に切り替え(pyenv shell)

今開いているターミナルだけ一時切り替えする場合に便利です。

Shell
pyenv shell 3.11.9
python -V
pyenv shell --unset  # 一時設定を解除
実行結果
Python 3.11.9

一時切り替えはターミナルを閉じると元に戻ります。

.python-versionの役割

.python-versionは「このディレクトリではどのPythonを使うか」を記録する小さなテキストファイルです。

Gitで共有すればチーム全員が同じバージョンを使えるため、再現性向上に役立ちます。

優先順位は次の通りです。

  • shellで指定した値
  • カレントディレクトリから上位へたどって最初に見つかった.python-version
  • globalで設定した値
注意

他OSのメンバーが同じバージョンをインストールしていないと切り替えに失敗します。

READMEなどに必要バージョンを明記しましょう。

以下の表に3つの切り替え方法の違いをまとめます。

コマンド適用範囲使いどころ
pyenv global X.Y.Z全体(既定)よく使うバージョンの基準を決める
pyenv local X.Y.Zカレントプロジェクトだけプロジェクト単位で固定したい時
pyenv shell X.Y.Z今のシェルだけ(一時的)サッと別バージョンを試したい時

まずglobalで基準をつくり、プロジェクトではlocalで固定するのが定石です。

実例: プロジェクトごとにPythonを固定する手順

ここでは3.12系をプロジェクトに固定する例を実演します。

実務でもほぼこの手順で通用します。

1. プロジェクト作成と移動

Shell
# 作業用ディレクトリを作成して移動
mkdir -p ~/work/py-sample
cd ~/work/py-sample

# 位置確認
pwd
実行結果
/home/you/work/py-sample

2. 必要なPythonをインストール(例: 3.12系)

Shell
# 利用可能な3.12系を確認
pyenv install -l | grep '^  3\.12\.' | tail -n 5  # 末尾5件の例

# インストール(まだなら)
pyenv install 3.12.6
実行結果
Installed Python-3.12.6 to /home/you/.pyenv/versions/3.12.6

3. プロジェクトに紐づけ(pyenv local 3.12.x)

Shell
# このプロジェクトだけ 3.12.6 を使う
pyenv local 3.12.6

# 作成されたファイルを確認
cat .python-version
実行結果
3.12.6

.python-versionがある限り、このフォルダでは常に3.12.6が有効です。

4. バージョン確認(python -V)

Shell
# バージョンと実体の場所を確認
python -V
which python

# Pythonからも確認
python -c "import sys; print(sys.version)"
実行結果
Python 3.12.6
/home/you/.pyenv/shims/python
3.12.6 (main, Aug 20 2024, 10:00:00) [GCC 12.2.0]

whichの結果がshims配下を指していれば設定は正しく機能しています。

VSCodeでインタプリタを選ぶ(Interpreter選択)

VSCodeを使う場合はインタプリタ選択が重要です。

次の手順でpyenvのPythonを選びます。

  1. コマンドパレットを開く(Windows/LinuxはCtrl+Shift+P、macOSはCmd+Shift+P)。
  2. Python: Select Interpreterを実行。
  3. 一覧から~/.pyenv/versions/3.12.6/bin/python(Windowsは%USERPROFILE%.pyenv\pyenv-win\versions\3.12.6\python.exe)を選ぶ。
  4. ワークスペースごとに固定したい場合は.vscode/settings.jsonに書き込みます。
JSON
{
  "python.defaultInterpreterPath": "/home/you/.pyenv/versions/3.12.6/bin/python"
}

さらに仮想環境を使う場合は、まずpyenvでバージョンを固定してから、そのPythonでvenvを作成します。

Shell
# プロジェクト直下に仮想環境を作成し有効化する例
python -m venv .venv
source .venv/bin/activate  # Windowsは .venv\Scripts\activate

# VSCodeではワークスペースのインタプリタとして .venv/bin/python を選択

pyenvでPythonの「版」を、venvでパッケージの「箱」を分離するのが実務の定番です。

よくあるつまずき(PATHが反映されない/シェル再起動)

PATHやシェルの状態でつまずくことが多いので、代表的な原因と対処をまとめます。

  • 初期化が効いていない
    eval "$(pyenv init -)"とPYENV_ROOT/PATHの行が~/.zshrcや~/.bashrcにあるかを確認し、exec $SHELL -lで再読み込みします。
Shell
# 何が実行されるかを確認
type -a python
echo $PATH
実行結果
python is /home/you/.pyenv/shims/python
python is /usr/bin/python
/home/you/.pyenv/shims:/home/you/.pyenv/bin:/usr/local/bin:/usr/bin:...
  • 端末のキャッシュが古い
    bash系ではhash -rでコマンドキャッシュをクリアできます。pipで新しいCLIを入れたあと、pyenv rehashが必要な場合もあります。
Shell
hash -r
pyenv rehash
  • ほかのディストリビュータのPythonが先に来ている
    AnacondaやHomebrewのpythonがPATHの先頭にあるとpyenvが効きません。shimsがPATHの先頭になるよう並び替えます。condaをお使いならconda config --set auto_activate_base falseで自動有効化を止めるのも有効です。
  • Windowsで反映されない
    新しいPowerShellやcmdを開き直してください。where pythonで解決先を確認し、%USERPROFILE%.pyenv\pyenv-win\shimsが先頭に近いことを確かめます。
PowerShell
where python
echo $env:Path
実行結果
C:\Users\you\.pyenv\pyenv-win\shims\python.exe
C:\Windows\py.exe
...

それでもダメなときは、設定ファイルの重複やタイポ、再起動忘れを見直してください。

最小構成で新しいユーザーやシェルを試すのも診断に有効です。

まとめ

この記事では、pyenvを使ってプロジェクトごとにPythonバージョンを切り替える方法を、インストールから初期化、基本コマンド、実例まで順を追って解説しました。

要点は次の通りです。

まず依存ライブラリを整えてpyenvを導入し、eval "$(pyenv init -)"でshimsを有効化します。

そのうえでpyenv installで必要バージョンを追加し、全体はpyenv global、プロジェクトはpyenv localで固定します。

VSCodeではインタプリタ選択でpyenvのPythonを指定し、必要ならvenvを併用します。

つまずきの多くはPATHと再読み込みが原因なので、shimsがPATHの先頭にあることと新しいシェルを開き直すことを常に確認すると解決が早いです。

これで、Pythonのバージョン違いに振り回されず、安心してプロジェクトを進められるはずです。

Python 実践TIPS - 開発環境とツール
この記事を書いた人
エーテリア編集部
エーテリア編集部

人気のPythonを初めて学ぶ方向けに、文法の基本から小さな自動化まで、実際に手を動かして理解できる記事を書いています。

クラウドSSLサイトシールは安心の証です。

URLをコピーしました！