pyenvとは？「インストール方法」や「使い方」を詳しく解説！

Pythonを使って開発をしていると、こんな悩みにぶつかることはありませんか？

  • あるプロジェクトはPython 3.10を使っているけど、別のプロジェクトは3.12じゃないと動かない…
  • システムにインストールされているPythonのバージョンを変更したら、他のプロジェクトが動かなくなった…
  • コンテナやデプロイ先の環境でも同じバージョンで動かしたい…
  • 本番環境と開発環境でバージョンが違ってて、トラブルになった…

そんなときに便利なのが、Pythonのバージョン管理ツール『pyenv（パイエンブ）』です！

この記事では、pyenvの概要・インストール方法・使い方・トラブル対応・アンインストールなどをわかりやすく解説します。

pyenvとは？

pyenvは、複数のPythonバージョンを一つのシステム上で簡単に切り替えて管理できるバージョン管理ツールです。つまり、1台のPCにPython 3.7、3.8、3.10、3.12など、複数のバージョンを共存させて使い分けることができます。

pyenvの特徴

  • 複数のPythonバージョンを共存させられる
  • プロジェクトごとに異なるバージョンを指定できる
  • 簡単にバージョンの切り替えが可能
  • OS標準のPythonを上書きせず、安全に管理できる
  • 開発コンテナやデプロイ時のPythonビルドにも便利

例えば、あるプロジェクトはPython 3.10で、別のプロジェクトは3.12で動かしたい、といった場面で「pyenv」が役立ちます。

Windowsで使うなら「pyenv-win」

Pythonの開発で便利なツール「pyenv」ですが、LinuxやmacOS専用のツールです。そのため、Windowsではそのまま使えません。

そこで登場したのが「pyenv-win」です。「pyenv-win」は、WindowsでpyenvのようにPythonバージョンを切り替えられるようにしたツールです。つまり、「Linux/macで使えるpyenvを、Windowsでも使えるようにしたツール」ということです。

これは、「pyenv-win」pyenvのフォーク（派生プロジェクト）として開発されています。

pyenvでよく使うコマンド

後ほど詳しく説明しますが、pyenvでよく使うコマンドを以下に示します。

コマンド説明
pyenv versionsインストール済みバージョン一覧
pyenv install --listインストール可能なPython一覧
pyenv install <version>指定バージョンをインストール
pyenv uninstall <version>指定バージョンをアンインストール
pyenv local <version>カレントディレクトリに適用
pyenv global <version>グローバルに適用
pyenv shell <version>セッション内のみ適用
pyenv which python実行されるPythonのフルパス表示

pyenvのインストール方法

① pyenv本体をクローンしてインストールする

まずはpyenvの本体をGitHubからダウンロード（クローン）します。ターミナルを開いて、以下のコマンドを実行してください。

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

実行結果の例

$ git clone https://github.com/pyenv/pyenv.git ~/.pyenv
Cloning into '/home/user01/.pyenv'...
remote: Enumerating objects: 26074, done.
remote: Counting objects: 100% (166/166), done.
remote: Compressing objects: 100% (63/63), done.
remote: Total 26074 (delta 130), reused 103 (delta 103), pack-reused 25908 (from 4)
Receiving objects: 100% (26074/26074), 6.09 MiB | 11.93 MiB/s, done.
Resolving deltas: 100% (17476/17476), done.

上記のコマンドを実行すると、カレントユーザーのホームディレクトリに.pyenv隠しディレクトリが作成されます（ユーザーがuser01であれば、ホームディレクトリは/home/user01です）。

コマンド実行後にホームディレクトリでll -aコマンドで確認すると、.pyenvディレクトリが作成されていることがわかります。

$ ll -a
total 48
drwxr-x---  8 user01 user01 4096 Aug  1 09:03 ./
drwxr-xr-x  3 root   root   4096 Apr 22  2024 ../
-rw-------  1 user01 user01  626 Aug  1 08:30 .bash_history
-rw-r--r--  1 user01 user01  220 Apr 22  2024 .bash_logout
-rw-r--r--  1 user01 user01 3771 Apr 22  2024 .bashrc
drwx------  3 user01 user01 4096 Aug  1 08:16 .cache/
drwxr-xr-x  3 user01 user01 4096 Aug  1 08:17 .dotnet/
-rw-r--r--  1 user01 user01    0 Aug  1 08:16 .motd_shown
-rw-r--r--  1 user01 user01  807 Apr 22  2024 .profile
drwxr-xr-x 12 user01 user01 4096 Aug  1 09:03 .pyenv/ ← 作られている！
-rw-r--r--  1 user01 user01    0 Apr 22  2024 .sudo_as_admin_successful
drwxr-xr-x  3 user01 user01 4096 Aug  1 08:17 .vscode-remote-containers/
drwxr-xr-x  5 user01 user01 4096 Aug  1 08:16 .vscode-server/
drwxr-xr-x  6 user01 user01 4096 Apr 22  2024 lsCommand/

② パス設定（.bashrcや.zshrcに追記）を行う

pyenvをインストールしただけではpyenvコマンドは使えません。シェルにpyenvの場所を教えるために、パスの設定をします。以下のコマンドを実行して、.bashrcファイルに設定を追記します（※Zshを使っている人は.zshrcに変更してください）。

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

WSL2を使っている場合

WSL2（Windows Subsystem for Linux）を使っている場合、意図せずWindowsにインストールされたpyenvパスを参照してしまうことがあります。Windowsにインストールされたpyenvパスを参照してしまう場合、2行目を以下のように変更してください。「$HOME/.pyenv/bin」を明示的に指定することで、WSL側のpyenvを優先させることができます。

echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc

③ シェルの設定ファイル（~/.bashrc）を再読み込みする

上の設定を反映させるため、sourceコマンドで.bashrcを再読み込みします。

source ~/.bashrc

④ pyenvがインストールされたかを確認する

以下のコマンドを実行して、pyenvのバージョンが表示されればインストール成功です。

pyenv --version

実行結果の例

$ pyenv --version
pyenv 2.6.5

pyenvでPythonをインストールする方法

① インストールできるPythonバージョンを確認する

以下コマンドを実行すると、インストールできるPythonバージョンを確認することができます。

pyenv install --list
以下のコマンドでも可
pyenv install -l

実行結果の例

$pyenv install --list
Available versions:
  2.1.3
  2.2.3
  2.3.7
  ...(以下略)

grepコマンドを用いると、絞り込むことができる（例：Python 3.12系を表示したいとき）。

$ pyenv install --list | grep 3.12
  3.12.0
  3.12-dev
  3.12.1
  ...(以下略)

②指定したバージョンのPythonをインストール

以下コマンドを実行すると、指定したバージョンのPythonをインストールできます。

例：3.12.11をインストール
pyenv install 3.12.11

エラーが発生した場合

最初に実行すると、以下のようにエラーになる可能性があります。

$ pyenv install 3.12.11
Downloading Python-3.12.11.tar.xz...
-> https://www.python.org/ftp/python/3.12.11/Python-3.12.11.tar.xz
Installing Python-3.12.11...

BUILD FAILED (Ubuntu 22.04 using python-build 2.6.5)

Inspect or clean up the working tree at /tmp/python-build.20250801092653.260312
Results logged to /tmp/python-build.20250801092653.260312.log

Last 10 log lines:
checking for --enable-universalsdk... no
checking for --with-universal-archs... no
checking MACHDEP... "linux"
checking for gcc... no
checking for cc... no
checking for cl.exe... no
checking for clang... no
configure: error: in `/tmp/python-build.20250801092653.260312/Python-3.12.11':
configure: error: no acceptable C compiler found in $PATH
See `config.log' for more details

これは、Pythonのビルドに必要な開発ツールやライブラリが不足しているためです。インストールエラーが出た場合は、以下のようにビルドに必要なパッケージを事前にインストールしましょう。

Ubuntu や Debian 系の場合↓

sudo apt update
sudo apt install build-essential libbz2-dev libdb-dev \
  libreadline-dev libffi-dev libgdbm-dev liblzma-dev \
  libncursesw5-dev libsqlite3-dev libssl-dev \
  zlib1g-dev uuid-dev tk-dev

sudo apt-get install -y make build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev python-openssl git

CentOS 系の場合↓

sudo yum groupinstall "development tools"
sudo yum install bzip2-devel gdbm-devel libffi-devel \
  libuuid-devel ncurses-devel openssl-devel readline-devel \
  sqlite-devel xz-devel zlib-devel tk-devel

必要なパッケージをインストールしたあと、再びpyenv installコマンドを実行します。

実行結果の例（成功した例）

$ pyenv install 3.12.11
Downloading Python-3.12.11.tar.xz...
-> https://www.python.org/ftp/python/3.12.11/Python-3.12.11.tar.xz
Installing Python-3.12.11...
Installed Python-3.12.11 to /home/user01/.pyenv/versions/3.12.11

このように表示されれば、指定したPythonバージョン（ここでは3.12.11）のインストールは成功です。

インストールされたPythonは、~/.pyenv/versions/に格納されています。

インストール済みPythonバージョンを確認する方法

Pythonの複数バージョンを管理していると、「どのバージョンがインストールされているのか」「今使われているのはどれか」を確認したくなりますよね。そんなときは、次のコマンドを使います。

pyenv versions

実行結果の例

$ pyenv versions
  system
  3.9.18
  3.10.18
  3.11.13
* 3.12.11 (set by /home/user01/.python-version)

アスタリスク（*）が現在使用中のバージョンです。上記の実行結果は3.9.18、3.10.18、3.11.13、3.12.11のPythonバージョンをインストールしており、今使用中のバージョンは3.12.11であることを示しています。

systemとは

システムに最初から入っているPythonのこと。分かりやすく言うと、Ubuntuなどに標準で付いてくるPythonです。pyenvとは無関係に元から使えるバージョンです。

set by…とは

どこでそのバージョンが指定されているかを示しています。上記の実行結果の場合、ホームディレクトリ（/home/user01）にある.python-versionファイルで「Python 3.12.11を使う」と設定されているという意味になります。

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

pyenvを使えば、プロジェクト単位・ユーザー単位・一時的にPythonのバージョンを切り替えることができます。ここでは、3つの切り替え方法と、それぞれの動作範囲や特徴を分かりやすく紹介します。

コマンド範囲説明
pyenv shell <version>一時的（そのシェルのみ）現在のターミナルセッションだけで使うバージョンを変更。
pyenv local <version>プロジェクト／ディレクトリ単位プロジェクトごとにバージョンを固定。.python-versionファイルがカレントディレクトリに作られる。
pyenv global <version>ユーザー全体ユーザーアカウント全体で使うPythonを設定。versionファイルが.pyenvディレクトリに作られる。

シェル指定（一時的に切り替え）

pyenv shell 3.12.11
  • 現在のターミナルセッションだけでPythonのバージョンを一時的に切り替えます。
  • ターミナルを閉じるとリセットされます。
  • 一時的に別のバージョンを試したいときに便利です。

ローカル指定（特定のディレクトリだけで切り替え）

pyenv local 3.12.11
  • カレントディレクトリ（今いる場所）に.python-versionファイルが作られます。
  • そのディレクトリと配下にいる間は、常にそのバージョンが使用されます。
  • プロジェクトごとにPythonバージョンを固定したいときに便利です。

グローバル指定（ユーザー全体）

pyenv global 3.12.11
  • ユーザー全体のデフォルトPythonを設定します。
  • versionファイルが.pyenvディレクトリが作られます。
  • 他にローカル指定やshell指定がなければ、このバージョンが使われます。

バージョンが決まる順番（優先順位）

pyenvは、次の優先順位に従って使用するPythonバージョンを決定します。上にあるものほど優先され、下の設定は上の設定がなければ有効になります。

  • 環境変数PYENV_VERSION
    • pyenv shell <version>などで一時的に設定された値。現在のシェルセッションだけ有効。
  • .python-versionファイル（ローカル指定）
    • pyenv local <version>によって作られたファイル。カレントディレクトリおよび配下で有効。
  • $(pyenv root)/versionファイル（グローバル指定）
    • pyenv global <version>によって作られるファイル。ユーザー全体のデフォルト設定。
    • pyenv rootは、pyenvがインストールされたルートディレクトリのパスを取得するためのコマンドです。通常は、/home/ユーザー名/.pyenvのようなパスが返ってきます。このコマンドを$(...)で囲むことで、その結果（文字列）をシェル内で展開できます。
  • それらがすべて未設定の場合
    • システムに最初から入っているPython（system）が使われます。

Pythonのアンインストール方法

pyenvを使ってインストールしたPythonは簡単に削除（アンインストール）することができます。不要になった古いバージョンなどを整理したいときに便利です。以下のようにpyenv uninstallコマンドを使います（例：Python 3.10.18をアンインストールしたい場合）。

pyenv uninstall 3.10.18

実行結果の例

$ pyenv uninstall 3.10.18
pyenv: remove /home/user01/.pyenv/versions/3.10.18? (y/N) y
pyenv: 3.10.18 uninstalled

pyenv uninstallで削除できるのは、pyenvでインストールしたPythonのみです。システム（OS）に最初から入っているsystemバージョンは削除できません。

削除後、pyenv versionsコマンドを実行して、アンインストールしたバージョンが一覧から消えていればOKです。

$ pyenv versions
  system
  3.9.18
  3.11.13
* 3.12.11 (set by /home/user01/.python-version)

現在使用中のPythonバージョンのパスを確認する方法

現在使用中のPythonバージョンが、実際にどのパスにあるものかを確認したい場合は、次のコマンドを使います。

pyenv which python

実行結果の例

$ pyenv which python
/home/user01/.pyenv/versions/3.12.11/bin/python

この例では、現在使用中のPythonは~/.pyenv/versions/3.12.11/にインストールされたものであることがわかります。

プロジェクトごとに異なるバージョンを使っていると、「今使われているのはどのPython？」と確認したくなる場面も多いので、pyenv which pythonは覚えておくと便利です。

本記事のまとめ

この記事では『pyenv』について、以下の内容を説明しました。

  • pyenvとは？
  • Windowsで使うなら「pyenv-win」
  • pyenvでよく使うコマンド
  • pyenvのインストール方法
  • pyenvでPythonをインストールする方法
  • インストール済みPythonバージョンを確認する方法
  • Pythonバージョンを切り替える方法
  • Pythonのアンインストール方法
  • 現在使用中のPythonバージョンのパスを確認する方法

Pythonのプロジェクトごとにバージョンを切り替えたい…そんな悩みを解決してくれるのが、pyenvです。

  • 複数のPythonバージョンを共存・管理できる
  • ディレクトリ単位でバージョンを固定できる
  • インストールも切り替えもコマンド一つで簡単！

LinuxやmacOSではpyenv、Windowsではpyenv-winを使えば、より柔軟で快適なPython開発環境を構築できます。

環境の違いによるトラブルを防ぎたい方、複数バージョンを使い分けたい方は、ぜひ一度pyenvを導入してみてください！

お読み頂きありがとうございました。

スポンサーリンク