pyenv徹底解説！ これ一つでPythonバージョン問題を解決

By /

pyenv徹底解説！ これ一つでPythonバージョン問題を解決

Python開発において、バージョンの管理は避けて通れない課題です。異なるプロジェクトで異なるPythonバージョンが必要になったり、システムにインストールされているPythonのバージョンが古かったり、パッケージの依存関係が衝突したり…。これらの「Pythonバージョン問題」は、開発者を悩ませることがよくあります。

しかし、心配はいりません。Pythonのバージョン管理ツールである「pyenv」を使えば、これらの問題は劇的に解決できます。

本記事では、pyenvとは何か、なぜ必要なのか、そしてどのように使うのかを、インストールから応用、さらにはトラブルシューティングまで、約5000語にわたって徹底的に解説します。この記事を読めば、あなたもPythonのバージョンを自在に操り、快適な開発環境を手に入れることができるでしょう。

1. はじめに：なぜPythonのバージョン管理が必要なのか？

Pythonは、Web開発、データサイエンス、機械学習、自動化スクリプト、システム管理など、非常に幅広い分野で利用されています。その人気の高まりとともに、多くのプロジェクトやライブラリが生まれ、それぞれが特定のPythonバージョンを要求することが増えてきました。

例えば、

  • 古いプロジェクトの保守: 数年前に開発されたプロジェクトは、Python 3.6や3.7などの少し前のバージョンで開発されているかもしれません。最新のPython 3.10や3.11で実行しようとすると、互換性の問題で動かないことがあります。
  • 新しいプロジェクトの開始: 最新のPythonバージョン（例: Python 3.11）で導入された新しい構文や機能を使いたい場合、そのバージョンが必要です。
  • 特定のライブラリの要件: ある機械学習ライブラリの古いバージョンはPython 3.8までしかサポートしていない、別の最新ライブラリはPython 3.9以上が必須、といったケースは頻繁にあります。
  • システムPythonの問題: OSにプリインストールされているPython（通称「システムPython」）は、セキュリティ上の理由などから古いバージョンであることが多く、また、システム全体で共有されているため、安易にパッケージをインストールしたりアップデートしたりすると、システムに影響を与える可能性があります。管理者権限が必要になることもあり、扱いが難しいです。

これらの状況が重なると、開発者は次のような問題に直面します。

  1. バージョンの衝突: あるプロジェクトではPython 3.7、別のプロジェクトではPython 3.9が必要、といった場合に、どのバージョンを使えば良いのかわからなくなります。
  2. パッケージの衝突: 同じライブラリでも、Pythonのバージョンやプロジェクトによって必要なバージョンが異なることがあります。システムPythonに globally パッケージをインストールしすぎると、依存関係が壊れてしまう「依存関係地獄（dependency hell）」に陥りやすくなります。
  3. 環境の再現性の問題: ある環境で動いていたコードが、別の環境（Pythonバージョンが異なる、インストールされているパッケージのバージョンが異なるなど）では動かないという問題が発生します。これは、共同開発やデプロイにおいて非常に困ります。

これらの問題を解決し、プロジェクトごとに独立した、クリーンで再現性の高いPython環境を構築するために、Pythonのバージョン管理ツールが必要になります。そして、そのための強力なツールの一つが「pyenv」なのです。

2. pyenvとは？

pyenvは、複数のPythonバージョンを同じシステム上に共存させ、簡単に切り替えられるようにするためのツールです。開発者がプロジェクトや用途に応じて、必要なPythonバージョンを自由に選択・利用できるようにします。

pyenvの最大の特徴は、システムにインストールされているPython環境に一切干渉せず、ユーザーのホームディレクトリ配下に必要なPythonバージョンをインストール・管理する点です。これにより、システムを汚染するリスクなく、安全に複数のPython環境を構築できます。

また、pyenvは PATH環境変数を汚染せず、shim (シム) と呼ばれる独自の仕組みを使ってPythonの実行ファイル（python, pip など）を切り替えます。これにより、シェルの設定ファイルに大量のPATHを追加することなく、スマートなバージョン切り替えを実現しています。

pyenv vs その他のツール

Pythonの開発環境管理には、pyenv以外にもいくつかのツールがあります。それぞれの目的とpyenvとの関係性を理解しておきましょう。

  • venv / virtualenv: これらは「仮想環境」を作成するためのツールです。仮想環境は、特定のPythonバージョン上に構築され、その環境専用のパッケージインストール領域を提供します。プロジェクトごとに独立したパッケージセットを持つことで、パッケージの依存関係衝突を防ぎます。
    • pyenvとの関係: pyenvはPythonの「バージョンそのもの」を管理し、venv/virtualenvは「特定のバージョン上に構築されるパッケージ環境」を管理します。両者は目的が異なるため、組み合わせて使うのが一般的かつ推奨される方法です。pyenvでまず目的のPythonバージョンをインストールし、そのバージョンの上にvenvやvirtualenvで仮想環境を作成します。
  • conda: AnacondaやMinicondaに含まれるパッケージ・環境管理ツールです。Pythonバージョン管理も可能ですが、主に科学計算やデータサイエンス分野でよく利用され、独自のパッケージリポジトリを持っています。
    • pyenvとの関係: condaもPythonバージョン管理が可能ですが、pyenvはより汎用的な、標準的なPythonディストリビューションの管理に特化しています。どちらか一方、あるいは目的に応じて使い分けることが多いです。pyenvはMinicondaやAnacondaのインストールもサポートしています。
  • Poetry / pipenv: これらはアプリケーションレベルの依存関係管理ツールです。プロジェクトが必要とするパッケージとPythonバージョンを定義ファイル（pyproject.toml や Pipfile）で管理し、自動的に仮想環境を作成してそこにパッケージをインストールします。
    • pyenvとの関係: Poetryやpipenvは、どのPythonバージョンを使うかを指定できます。この際、pyenvでインストールされた特定のPythonバージョンをPoetryやpipenvに使用させることで、さらに柔軟な環境構築が可能になります。pyenvでシステム全体のデフォルトバージョンを設定し、Poetry/pipenvでプロジェクトごとの仮想環境とパッケージを管理するという組み合わせは非常に強力です。

このように、pyenvはPythonの「バージョンそのもの」のインストールと切り替えに特化しており、venv/virtualenvやPoetry/pipenvといった他のツールと組み合わせて使うことで、より堅牢で効率的な開発環境を構築できます。

3. pyenvのインストール

pyenvを使い始めるには、まずシステムにインストールする必要があります。インストール方法はOSによって異なりますが、macOSとLinuxでは比較的簡単です。Windowsについては別途「pyenv-win」というプロジェクトがありますが、本記事ではmacOSやLinuxなどのUnix系システムに焦点を当てて解説します。

macOS (Homebrewを使用)

macOSでは、パッケージマネージャーであるHomebrewを使うのが最も簡単です。

  1. Homebrewのインストール: Homebrewがまだインストールされていない場合は、公式サイト (https://brew.sh/) を参照してインストールしてください。

  2. pyenvのインストール: ターミナルを開き、以下のコマンドを実行します。

    bash
    brew update
    brew install pyenv

  3. シェルの設定: pyenvを使うためには、シェルの設定ファイル（.bashrc, .zshrc, .profile など）にpyenvを初期化するための設定を追記する必要があります。使用しているシェルによってファイルが異なります。

    • Bashの場合:
      bash
      echo 'eval "$(pyenv init --path)"' >> ~/.bash_profile
      echo 'eval "$(pyenv init -)"' >> ~/.bash_profile
      または、.bashrc を使っている場合は .bashrc に追記します。

    • Zshの場合:
      bash
      echo 'eval "$(pyenv init --path)"' >> ~/.zshrc
      echo 'eval "$(pyenv init -)"' >> ~/.zshrc

    • Fishの場合:
      fish
      echo 'pyenv init --path | source' >> ~/.config/fish/config.fish
      echo 'pyenv init - | source' >> ~/.config/fish/config.fish

    多くのモダンなmacOS環境ではZshがデフォルトシェルです。上記のコマンドを実行することで、pyenvのshimパス（実行ファイルを切り替えるためのディレクトリ）がPATH環境変数に追加され、シェルの起動時にpyenvが初期化されるようになります。

  4. 設定の反映: 設定ファイルを編集したら、以下のコマンドを実行するか、ターミナルを再起動して設定を反映させます。

    bash
    source ~/.zshrc # Zshの場合。Bashの場合は ~/.bash_profile など

  5. インストールの確認: pyenvコマンドが実行できるか、バージョンが正しく認識されているかを確認します。

    bash
    pyenv --version
    pyenv versions
    type python

    pyenv --version でバージョン情報が表示され、pyenv versions で利用可能なバージョンが表示され（この時点ではsystemのみ）、type python で python is a function または python is ~/.pyenv/shims/python のような出力が表示されれば、インストールと設定は成功です。

Linux (インストーラースクリプトを使用)

Linuxディストリビューション（Ubuntu, Debian, Fedora, CentOSなど）では、公式が提供するインストーラースクリプトを使うのが便利です。

  1. 依存ライブラリのインストール: pyenvでPythonをビルドするためには、いくつかの開発ツールやライブラリが必要です。ディストリビューションによってコマンドが異なります。

    • Debian/Ubuntu系:
      bash
      sudo apt-get update
      sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
      libreadline-dev libsqlite3-dev wget curl llvm libncursesw5-dev xz-utils \
      tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
    • Fedora/CentOS/RHEL系:
      bash
      sudo yum update -y # または dnf update -y
      sudo yum install -y zlib-devel bzip2-devel openssl-devel readline-devel \
      sqlite-devel gcc gcc-c++ make libffi-devel

    これらの依存ライブラリが不足していると、後でPythonバージョンをインストールする際にビルドエラーが発生します。上記のコマンドは一般的なものであり、環境によっては追加のライブラリが必要になる場合もあります。

  2. pyenvのインストール: 以下のコマンドを実行してインストーラースクリプトを実行します。

    bash
    curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash

    このスクリプトは、pyenv本体、pyenv-virtualenv プラグイン、pyenv-update プラグインなどをユーザーのホームディレクトリ（デフォルトは ~/.pyenv）にクローンし、シェルの設定方法を案内してくれます。

  3. シェルの設定: インストーラーの案内に従って、シェルの設定ファイル（.bashrc, .zshrc など）に以下の内容を追記します。

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

    • export PATH="$HOME/.pyenv/bin:$PATH": pyenvコマンド自体を使えるようにPATHを追加します。
    • eval "$(pyenv init --path)": pyenvのshimパス（$PYENV_ROOT/shims）をPATHに追加します。これがバージョン切り替えの要となります。
    • eval "$(pyenv init -)": シェル関数や環境変数を設定し、pyenvが正しく動作するように初期化します。
    • eval "$(pyenv virtualenv-init -)": 後述する pyenv-virtualenv プラグインを初期化し、仮想環境の自動アクティベートなどができるようにします。

    .bashrc などの設定ファイルを開き、これらの行を追記してください。ファイルの末尾に追記するのが一般的です。

  4. 設定の反映: 設定ファイルを編集したら、以下のコマンドを実行するか、ターミナルを再起動して設定を反映させます。

    bash
    source ~/.bashrc # Bashの場合。Zshの場合は ~/.zshrc など

  5. インストールの確認: macOSと同様に確認します。

    bash
    pyenv --version
    pyenv versions
    type python

    同様の出力が得られれば成功です。

pyenv-win (Windows)

Windows環境では、公式のpyenvは直接動作しません。代わりに、コミュニティによって開発されている「pyenv-win」というツールがあります。インストール方法やコマンド体系がUnix系のpyenvとは異なるため、本記事では詳細な解説は割愛しますが、Windowsでpyenvと同様のバージョン管理を行いたい場合は、pyenv-winのGitHubページ を参照してください。PowerShellやcmd.exeでの利用が可能です。

4. pyenvの基本的な使い方

pyenvのインストールと設定が完了したら、いよいよPythonバージョンのインストールと切り替えを行ってみましょう。

4.1. インストール可能なPythonバージョンの確認

pyenvでインストールできるPythonのバージョンを確認するには、pyenv install --list コマンドを使います。

bash
pyenv install --list

実行すると、Cinder、Jython、Miniconda、Anaconda、pypy、Stackless、標準的なCPythonなど、非常に多くのバージョンが表示されます。

Available versions:
2.1.3
2.2.3
... (省略) ...
3.9.16
3.10.10
3.11.2
3.12.0
... (省略) ...
anaconda3-2023.03
miniconda3-latest
... (省略) ...
pypy3.9-7.3.10
... (省略) ...

リストの中から、インストールしたいバージョン名（例: 3.10.10, 3.12.0 など）を確認します。

4.2. Pythonバージョンのインストール

インストールしたいバージョンが決まったら、pyenv install <version> コマンドでインストールします。例えば、Python 3.12.0をインストールするには以下のように実行します。

bash
pyenv install 3.12.0

このコマンドを実行すると、pyenvはインターネットから指定したバージョンのPythonのソースコードをダウンロードし、システム上でコンパイル（ビルド）してインストールします。このプロセスは時間がかかる場合があります。また、前述した依存ライブラリが不足していると、ビルド途中でエラーが発生してインストールに失敗することがあります。エラーメッセージをよく読み、不足しているライブラリをインストールしてから再度試みてください。

複数のバージョンをインストールすることも可能です。

bash
pyenv install 3.9.16
pyenv install 3.11.2

インストールされたPythonの実行ファイルやライブラリは、デフォルトでは ~/.pyenv/versions/<version> ディレクトリ以下に格納されます。

4.3. インストール済みのPythonバージョンの確認

現在システム（正確にはpyenv）にインストールされているPythonバージョンを確認するには、pyenv versions コマンドを使います。

bash
pyenv versions

以下のような出力が得られます。

system
3.9.16
3.11.2
* 3.12.0 (set by /Users/yourname/.pyenv/version)

出力の意味は以下の通りです。

  • system: システムにプリインストールされている、pyenvが管理していないデフォルトのPythonバージョンを示します。
  • 3.9.16, 3.11.2, 3.12.0: pyenvでインストールしたPythonのバージョンです。
  • 行頭の *: 現在アクティブ（使用されている）なバージョンを示します。
  • 括弧内の情報: そのバージョンがどの設定（global, local, shell）によってアクティブになっているかを示します。この例では、.pyenv/version ファイル（pyenv global で設定されるファイル）によってPython 3.12.0がアクティブになっていることを示しています。

4.4. Pythonバージョンの切り替え

pyenvの主な機能は、複数のバージョンの中から現在使用するバージョンを切り替えることです。切り替えにはいくつかのスコープ（適用範囲）があります。

  • global: システム全体（正確にはユーザー全体）のデフォルトバージョンを設定します。どのディレクトリにいても、特に設定がなければこのバージョンが使われます。
  • local: 現在のディレクトリ（およびそのサブディレクトリ）でのみ有効なバージョンを設定します。プロジェクトごとに特定のバージョンを使いたい場合に利用します。設定すると、そのディレクトリに .python-version というファイルが作成されます。
  • shell: 現在のシェルセッションでのみ有効なバージョンを設定します。一時的に特定のバージョンで作業したい場合に利用します。シェルの環境変数 PYENV_VERSION が設定されます。

これらの設定は、shell > local > global の優先順位で適用されます。つまり、shell設定があればそれが最優先され、なければlocal設定、それもなければglobal設定、global設定もなければsystem Pythonが使われます。

グローバルバージョンの設定 (pyenv global)

システム全体のデフォルトとしてPython 3.12.0を使いたい場合は、以下のコマンドを実行します。

bash
pyenv global 3.12.0

実行後、pyenv versions を確認すると、3.12.0 に * が付いているはずです。~/.pyenv/version ファイルにバージョン名が書き込まれます。

ローカルバージョンの設定 (pyenv local)

特定のプロジェクトディレクトリでPython 3.9.16を使いたい場合は、そのディレクトリに移動してから以下のコマンドを実行します。

bash
cd path/to/my_project
pyenv local 3.9.16

実行すると、現在のディレクトリに .python-version というファイルが作成され、その中に 3.9.16 と記述されます。このディレクトリ内でコマンドを実行すると、Python 3.9.16が使用されるようになります。

“`bash

プロジェクトディレクトリ内で

pyenv versions

system

3.9.16

3.11.2

* 3.12.0 (set by /Users/yourname/.pyenv/version) <- global設定

3.14.1 (set by /Users/yourname/path/to/my_project/.python-version) <- local設定

ローカルバージョンが設定されているディレクトリに移動すると * が変わる

cd path/to/my_project
pyenv versions

system

* 3.9.16 (set by /Users/yourname/path/to/my_project/.python-version)

3.11.2

3.12.0

別のディレクトリに移動すると global 設定に戻る

cd ..
pyenv versions

system

3.9.16

3.11.2

* 3.12.0 (set by /Users/yourname/.pyenv/version)

“`

シェルバージョンの設定 (pyenv shell)

一時的に、現在のターミナルセッションでのみPython 3.11.2を使いたい場合は、以下のコマンドを実行します。

bash
pyenv shell 3.11.2

これは現在のシェルセッションの環境変数 PYENV_VERSION を設定するだけで、ファイルは作成されません。新しいターミナルを開いたり、シェルセッションを終了したりすると、この設定は失われます。

“`bash

shell 設定後

pyenv versions

system

3.9.16

* 3.11.2 (set by PYENV_VERSION environment variable)

3.12.0

“`

shell設定を解除するには、引数を指定せずに pyenv shell を実行するか、シェルを再起動します。

bash
pyenv shell --unset

4.5. 設定されたバージョンの確認

現在アクティブになっているPythonバージョンを確認するには、pyenv version (単数形) コマンドを使います。

bash
pyenv version

出力は pyenv versions の * が付いている行と同じ情報を示します。

“`bash

global 設定が有効な場合

pyenv version

3.12.0 (set by /Users/yourname/.pyenv/version)

local 設定が有効なディレクトリ内で

cd path/to/my_project
pyenv version

3.9.16 (set by /Users/yourname/path/to/my_project/.python-version)

shell 設定が有効な場合

pyenv shell 3.11.2
pyenv version

3.11.2 (set by PYENV_VERSION environment variable)

“`

4.6. Python実行ファイルの確認 (which python)

pyenvが正しく動作しているかを確認するもう一つの方法は、which python コマンドを使うことです。pyenvが管理するPythonがアクティブになっている場合、このコマンドは常に ~/.pyenv/shims/python を出力します。

“`bash
which python

/Users/yourname/.pyenv/shims/python

“`

これは、pyenvがPATH環境変数に ~/.pyenv/shims を追加し、そこに置かれた python という実行ファイル（shim）が、実際のPython実行ファイル（~/.pyenv/versions/<version>/bin/python）への橋渡しをしているためです。

このshimの仕組みこそが、pyenvが複数のPythonバージョンをPATH環境変数を複雑にすることなく管理できる鍵です。あなたが python <script.py> とコマンドを実行すると、シェルのPATH設定によりまず ~/.pyenv/shims/python が実行されます。このshimスクリプトが、現在のpyenv設定（shell > local > global）に基づいて、どのPythonバージョンを使うべきかを判断し、該当するバージョンの実際の python 実行ファイルに処理をリダイレクトする、という流れになっています。

5. 実践的な使い方と応用

pyenvの基本的な使い方が分かったところで、実際の開発シーンでどのように活用するのかを見ていきましょう。

5.1. プロジェクトごとのバージョン管理 (pyenv local)

最も一般的な使い方は、プロジェクトごとに独立したPythonバージョンを設定することです。これは pyenv local コマンドを使って行います。

新しいプロジェクトを開始する際のワークフローは以下のようになります。

  1. プロジェクトディレクトリを作成し、移動する:
    bash
    mkdir my_new_project
    cd my_new_project
  2. プロジェクトで使用したいPythonバージョンを指定する:
    pyenv install --list で確認し、必要であれば pyenv install <version> でインストールしておきます。
    bash
    pyenv local 3.10.10
    これにより、my_new_project ディレクトリに .python-version ファイルが作成されます。
  3. バージョンが正しく設定されたか確認する:
    bash
    pyenv version
    which python
    python --version
    python --version で Python 3.10.10 と表示されれば成功です。
  4. （推奨）このバージョン上に仮想環境を作成する:
    パッケージ管理をクリーンに行うために、この後解説する仮想環境（venvやpyenv virtualenv）を作成してアクティベートします。
  5. 必要なパッケージをインストールする:
    仮想環境がアクティベートされた状態で、pipやPoetryを使ってパッケージをインストールします。これらのパッケージは、このプロジェクト専用の仮想環境にのみインストールされます。

既存のプロジェクトに参加する際のワークフローはさらに簡単です。

  1. プロジェクトリポジトリをクローンする:
    bash
    git clone <repository_url>
    cd <project_directory>
  2. .python-version ファイルがあれば、pyenvが自動的にバージョンを切り替える:
    ディレクトリ移動時に、もし .python-version ファイルが存在すれば、pyenvは自動的にそのファイルに記述されたバージョンをアクティブにしようとします。
  3. もし必要なPythonバージョンがインストールされていなければインストールする:
    pyenv versions で必要なバージョンに * が付いていない場合（または pyenv version でエラーが出る場合）、そのバージョンがまだシステムにインストールされていません。
    bash
    pyenv install $(cat .python-version)
    .python-version ファイルからバージョン名を読み取ってインストールします。
  4. バージョンが正しく設定されたか確認する:
    bash
    pyenv version
    which python
    python --version
  5. （推奨）プロジェクトの仮想環境をセットアップする:
    プロジェクトが仮想環境（venv, Poetry, pipenvなど）を使っている場合は、その指示に従って環境をセットアップします。

この pyenv local を使うことで、ディレクトリを移動するだけで自動的に適切なPythonバージョンに切り替わるため、非常に効率的に複数のプロジェクトを行き来できるようになります。

5.2. 特定バージョンでのスクリプト実行 (pyenv exec)

現在アクティブになっているバージョンとは異なる特定のバージョンで一度だけスクリプトを実行したい場合があります。このような場合は pyenv exec コマンドが便利です。

例えば、現在Python 3.10がアクティブだが、Python 3.9で特定のスクリプトを実行したい場合：

bash
pyenv exec 3.9.16 python your_script.py

これは ~/.pyenv/versions/3.9.16/bin/python your_script.py とほぼ同じ意味ですが、pyenv exec を使うことでpyenvのバージョン解決機構を通して実行されるため、より厳密にpyenv管理下の環境として実行できます。

また、特定のバージョンの pip やその他のコマンドを実行する際にも使えます。

bash
pyenv exec 3.9.16 pip install some_package

5.3. Pythonバージョンのアンインストール

不要になったPythonバージョンは pyenv uninstall <version> コマンドで削除できます。

bash
pyenv uninstall 3.9.16

これにより、~/.pyenv/versions/3.9.16 ディレクトリ以下のファイルが削除され、そのバージョンは利用できなくなります。

5.4. 再インストールまたはビルドエラーへの対処法

Pythonのインストールに失敗したり、インストール済みのバージョンに問題が発生したりした場合は、一度アンインストールしてから再度インストールを試みるのが有効です。

bash
pyenv uninstall <version>
pyenv install <version>

ビルドエラーが発生した場合は、そのエラーメッセージを注意深く確認してください。多くの場合、Pythonのビルドに必要な依存ライブラリがシステムにインストールされていないことが原因です。前述した「依存ライブラリのインストール」セクションを参照し、エラーメッセージで示唆されているライブラリ名や関連キーワード（例: zlib, libffi, ssl, readlineなど）を参考に、必要なライブラリをシステムにインストールしてから再度 pyenv install を実行してください。

6. pyenvと仮想環境（venv, virtualenv）の連携

pyenvでPythonバージョンを管理するだけでは、パッケージの依存関係問題は完全に解決できません。なぜなら、同じPythonバージョンを使っている複数のプロジェクトで、異なるバージョンの同じライブラリが必要になる可能性があるからです。

この問題を解決するのが「仮想環境」です。仮想環境は、特定のPythonバージョン上に構築され、その環境内でインストールされるパッケージを他の環境から完全に隔離します。

6.1. なぜ仮想環境が必要なのか？

  • 依存関係の分離: プロジェクトAが必要とするライブラリのバージョンと、プロジェクトBが必要とする同じライブラリのバージョンが異なっていても、それぞれのプロジェクトで独立した仮想環境を使っていれば衝突しません。
  • クリーンな環境: プロジェクトに必要な最小限のパッケージだけをインストールできます。
  • 再現性の確保: requirements.txt やその他の依存関係定義ファイルと組み合わせることで、他の開発者やデプロイ環境でも同じパッケージ構成を再現できます。
  • システム汚染の回避: システムPythonやpyenvでインストールした基本バージョンのサイトパッケージを汚染するのを防ぎます。

pyenvはPythonバージョンそのものを管理しますが、仮想環境はそのバージョン上で動作する独立したパッケージ環境を管理します。これらは補完的な関係にあり、組み合わせて使うのがPython開発におけるベストプラクティスとされています。

6.2. pyenv virtualenv プラグイン

pyenvでインストールした特定のPythonバージョン上に仮想環境を作成・管理するために、「pyenv-virtualenv」という公式プラグインが提供されています。多くのpyenvインストーラーにはこのプラグインも含まれています。

pyenv-virtualenvのインストール

pyenv installer script (Linux) を使ってpyenvをインストールした場合、通常はpyenv-virtualenvも一緒にインストールされています。Homebrew (macOS) の場合は、別途インストールが必要な場合があります。

bash
brew install pyenv-virtualenv

インストール後、前述したようにシェルの設定ファイルに eval "$(pyenv virtualenv-init -)" が追記されていることを確認し、設定を反映させてください。

仮想環境の作成 (pyenv virtualenv)

pyenv-virtualenvを使って仮想環境を作成するには、以下のコマンドを使います。

bash
pyenv virtualenv <python_version> <environment_name>

  • <python_version>: 仮想環境のベースとなるPythonバージョン。pyenv versions で表示されるいずれかのバージョンを指定します。
  • <environment_name>: 作成する仮想環境の名前。プロジェクト名などを分かりやすく付けます。

例: Python 3.10.10をベースにした my-project-env という名前の仮想環境を作成

bash
pyenv virtualenv 3.10.10 my-project-env

このコマンドを実行すると、指定したバージョンのPythonがインストールされていなければインストールを促され、~/.pyenv/versions/<environment_name> ディレクトリに仮想環境が作成されます。

作成された仮想環境は pyenv versions のリストにも表示されます。

“`bash
pyenv versions

system

3.9.16

* 3.10.10 (set by /path/to/current/dir/.python-version)

3.11.2

3.12.0

3.10.10/envs/my-project-env <- 仮想環境のベースバージョン表示

my-project-env <- 仮想環境名で表示

“`

3.10.10/envs/my-project-env という形式は、この仮想環境がどのPythonバージョンをベースにしているかを示しています。my-project-env という名前は、この仮想環境をアクティベートしたりローカル設定したりする際に使用する名前です。

仮想環境の有効化 (pyenv activate)

作成した仮想環境を現在のシェルセッションで有効にするには、以下のコマンドを使います。

bash
pyenv activate <environment_name>

例: my-project-env を有効化

bash
pyenv activate my-project-env

仮想環境が有効化されると、シェルのプロンプトの先頭に仮想環境名が表示されることが多く、python や pip コマンドがその仮想環境内のものを指すようになります。

“`bash
(my-project-env) $ python –version

Python 3.10.10

(my-project-env) $ which python

/Users/yourname/.pyenv/versions/my-project-env/bin/python

“`

この状態で pip install <package> と実行すれば、パッケージはその仮想環境内にのみインストールされます。

仮想環境の無効化 (pyenv deactivate)

有効化された仮想環境を無効にするには、以下のコマンドを使います。

bash
pyenv deactivate

プロンプトの仮想環境名が消え、pyenv local/global 設定に戻ります。

仮想環境の削除 (pyenv uninstall または pyenv virtualenv-delete)

不要になった仮想環境を削除するには、pyenv uninstall <environment_name> コマンドを使います（これは pyenv virtualenv-delete のエイリアスです）。

“`bash
pyenv uninstall my-project-env

または pyenv virtualenv-delete my-project-env

“`

これにより、~/.pyenv/versions/my-project-env ディレクトリ以下が削除されます。

6.3. pyenv local と仮想環境の自動アクティベート

pyenv-virtualenv プラグインを初期化 (eval "$(pyenv virtualenv-init -)") している場合、pyenv local コマンドを使ってディレクトリに仮想環境名を設定すると、そのディレクトリに移動した際に自動的に仮想環境がアクティベートされるようになります。

  1. 仮想環境を作成する:
    bash
    pyenv virtualenv 3.11.2 my-other-project-env
  2. プロジェクトディレクトリに移動する:
    bash
    cd path/to/my_other_project
  3. そのディレクトリのローカル設定として仮想環境名を指定する:
    bash
    pyenv local my-other-project-env
    これにより、.python-version ファイルに my-other-project-env と記述されます。
  4. ディレクトリを移動する:
    path/to/my_other_project ディレクトリに移動すると、自動的に my-other-project-env 仮想環境がアクティベートされます。他のディレクトリからこのディレクトリに cd して入った際にも自動でアクティベートされます。

この機能は、プロジェクトごとに異なるPythonバージョンとパッケージ環境が必要な場合に非常に便利です。ディレクトリ移動だけで適切な環境がセットアップされるため、手動で activate する手間が省けます。

6.4. pyenvとvenv/virtualenvの役割分担

まとめると、pyenvとvenv/virtualenv（またはpyenv-virtualenv）は以下のように役割分担し、連携するのが理想的です。

  • pyenv: システムにインストールするPythonの「バージョンそのもの」を管理。複数のバージョンを共存させ、プロジェクトやグローバル設定に応じて「どのバージョンのPythonを使うか」を切り替える役割。
  • venv/virtualenv (pyenv-virtualenv): 特定のPythonバージョン上に構築される「パッケージ環境」を管理。プロジェクトごとに独立したパッケージセットを持ち、「どのパッケージ群を使うか」を分離する役割。

つまり、まずpyenvでプロジェクトに必要なPythonバージョンをインストールし、次にそのバージョン上にvenvまたはpyenv-virtualenvで仮想環境を作成し、最後にその仮想環境内でパッケージをインストールする、という流れになります。

7. pyenvとその他のPython開発ツール

pyenvは、Poetryやpipenvといった現代的な依存関係管理ツールとも組み合わせて使用できます。

7.1. Poetry との連携

Poetryは、依存関係管理、パッケージング、パブリッシングなどを統合的に行うツールです。プロジェクトの依存関係と使用するPythonバージョンを pyproject.toml ファイルで定義します。Poetryは、プロジェクトに必要なPythonバージョンを検出し、自動的に仮想環境を作成して管理する機能を持ちます。

pyenvとPoetryを組み合わせる場合、pyenvでシステムレベルで必要なPythonバージョンをインストールしておき、Poetryがプロジェクトの pyproject.toml で指定されたPythonバージョン（pyenvでインストールされたもの）を使用して仮想環境を作成する、という流れが一般的です。

  1. pyenvでPythonバージョンをインストール:
    プロジェクトが必要とするPythonバージョンをpyenvでインストールしておきます。
    bash
    pyenv install 3.10.10
  2. Poetryプロジェクトを作成または既存のプロジェクトに移動:
    bash
    poetry new my_poetry_project
    cd my_poetry_project
  3. プロジェクトで使用するPythonバージョンを指定:
    pyproject.toml の [tool.poetry.dependencies] セクションでPythonバージョンを指定します。
    toml
    [tool.poetry.dependencies]
    python = "^3.10" # 3.10系ならどのバージョンでも良い
    または、特定のバージョンを指定する場合。
    toml
    [tool.poetry.dependencies]
    python = "3.10.10" # 厳密に3.10.10を使う
  4. pyenv localでプロジェクトのデフォルトPythonバージョンを設定 (推奨):
    PoetryはシステムPATHやpyenvでアクティブになっているPythonを使用して仮想環境を作成しようとします。プロジェクトディレクトリで pyenv local <version> を設定しておくと、Poetryがそのバージョンを使ってくれることが期待できます。
    bash
    pyenv local 3.10.10
  5. Poetry install を実行:
    bash
    poetry install
    Poetryは pyproject.toml を読み込み、適切なPythonバージョン（pyenvで指定したバージョンなど）を使って仮想環境を作成し、依存パッケージをインストールします。

Poetryが作成する仮想環境は、デフォルトではpyenvが管理するディレクトリとは別の場所に作成されることが多いです（例えば、システムのテンポラリディレクトリやプロジェクトルートの .venv など）。Poetryの config settings.virtualenvs.in-project true 設定でプロジェクトルートに .venv を作成するように変更することも可能です。

poetry env use <python_version_or_path> コマンドで、pyenvでインストールした特定のバージョンのPythonをPoetryの仮想環境作成に使用させることもできます。例えば poetry env use 3.10.10 と実行すると、pyenvでインストールした3.10.10を使用して仮想環境がセットアップされます。

7.2. pipenv との連携

pipenvもPoetryと同様に、プロジェクトごとの依存関係管理と仮想環境管理を行うツールです。Pipfile と Pipfile.lock を使います。

pyenvとpipenvを組み合わせる場合も、pyenvで必要なPythonバージョンをインストールしておき、pipenvにそのバージョンを使わせる、という流れです。

  1. pyenvでPythonバージョンをインストール:
    bash
    pyenv install 3.9.16
  2. プロジェクトディレクトリに移動:
    bash
    cd path/to/my_pipenv_project
  3. pipenvに特定のPythonバージョンを指定して仮想環境を作成:
    bash
    pipenv --python 3.9.16
    または、pyenvでローカル設定したバージョンを使用させる。
    bash
    pyenv local 3.9.16
    pipenv --python $(pyenv which python) # pyenvでアクティブなpythonのパスを渡す
    pipenv --python <version> を実行すると、指定したバージョンのPythonが見つかればそれを使って仮想環境が作成されます。pyenvが管理するバージョンは、pyenv which <version> でパスを取得できます。
  4. パッケージをインストール:
    bash
    pipenv install requests

pyenvは、様々なPython開発ツールと組み合わせて、柔軟で堅牢な開発環境を構築するための基盤として機能します。

7.3. IDEとの連携

VS CodeやPyCharmなどの統合開発環境（IDE）を使用している場合、IDEの設定でプロジェクトが使用するPythonインタプリタを指定する必要があります。pyenvでインストールしたPythonバージョンや仮想環境も、これらのIDEから容易に選択できます。

  • VS Code: Python拡張機能をインストールしている場合、ウィンドウの左下やコマンドパレット (Cmd/Ctrl+Shift+P -> Python: Select Interpreter) から利用可能なインタプリタを選択できます。pyenvでインストールしたバージョン（~/.pyenv/versions/<version>/bin/python）や、pyenv-virtualenvで作成した仮想環境（~/.pyenv/versions/<env_name>/bin/python）、あるいはPoetry/pipenvが作成した仮想環境内のPythonなどが自動的に検出され、リストに表示されることが多いです。必要に応じてパスを手動で追加することも可能です。
  • PyCharm: プロジェクト設定の「Project Interpreter」画面で、使用するPythonインタプリタを選択します。「Add Interpreter」から「Poetry Environment」や「Virtualenv Environment」などを選択し、pyenv管理下のパス（例: ~/.pyenv/versions/<version>/bin/python や ~/.pyenv/versions/<env_name>/bin/python）を指定することで、pyenvでセットアップした環境をPyCharmで使用できます。

IDEと連携することで、コード補完、デバッグ、テスト実行などが、プロジェクトで設定した正確なPythonバージョンとパッケージ環境で行えるようになります。

8. トラブルシューティングとよくある質問

pyenvのインストールや使用中に遭遇しやすい問題とその解決策、およびよくある質問について説明します。

8.1. python: command not found エラー

pyenvをインストールしたのに python コマンドが実行できない、またはシステムPythonが使われてしまう場合、最も可能性が高い原因はシェルの設定が正しく行われていないことです。

  • 確認ポイント:

    1. シェルの設定ファイル（.bashrc, .zshrc, .bash_profile など）に、pyenvの初期化コード（export PATH="$HOME/.pyenv/bin:$PATH", eval "$(pyenv init --path)", eval "$(pyenv init -)" など）が正しく追記されているか確認してください。特に eval "$(pyenv init --path)" が重要です。
    2. 設定ファイルを編集した後、source <設定ファイル名> を実行するか、ターミナルを再起動して設定を反映させましたか？
    3. echo $PATH を実行し、~/.pyenv/shims ディレクトリがPATHに含まれているか確認してください。そして、~/.pyenv/bin ディレクトリがそれよりも前に含まれているか確認してください。

  • 解決策:

    • シェルの設定ファイルを修正し、source コマンドを実行するかターミナルを再起動してください。
    • インストーラースクリプトをもう一度実行して、出力される設定方法を再確認してください。

8.2. インストール時のビルドエラー

pyenv install <version> 実行中にエラーが発生する場合、Pythonのビルドに必要な依存ライブラリが不足している可能性が高いです。

  • 確認ポイント:

    1. エラーメッセージを注意深く読んでください。zlib, libffi, ssl, readline, sqlite3, bzip2, tk などのキーワードが含まれていないか確認してください。
    2. お使いのOS/ディストリビューションに必要な依存ライブラリがインストールされているか確認してください。

  • 解決策:

    • 本記事の「3. pyenvのインストール」セクションにある、お使いのOSに対応した依存ライブラリのインストールコマンドを実行してください。
    • エラーメッセージに含まれるキーワードで検索し、不足している特定のライブラリをインストールしてください。
    • 依存ライブラリをインストールした後、pyenv uninstall <version> で失敗したバージョンを一度削除し、再度 pyenv install <version> を実行してください。
    • より詳細なビルドログを確認するには、PYENV_BUILD_LOG_PATH=/tmp/pyenv-build.log pyenv install <version> のように環境変数を設定して実行すると、ログファイルに詳細が出力されます。

8.3. PATHが正しく設定されない

echo $PATH を見ても .pyenv/shims や .pyenv/bin が含まれていない場合、または含まれているがシェルの設定ファイルを直接編集していないのに謎のpyenv関連パスが含まれている場合など。

  • 確認ポイント:

    1. 複数のシェルの設定ファイル（例: .bash_profile と .bashrc, .zshrc と .profile など）を混在させていないか確認してください。設定が重複したり、打ち消し合ったりすることがあります。
    2. 他のPython関連ツール（例: Anaconda, miniforgeなど）のPATH設定が邪魔をしていないか確認してください。一時的にそれらの設定をコメントアウトしてpyenvの設定だけを有効にしてみると原因が特定できることがあります。
    3. シェルの設定ファイル（.bashrc, .zshrc など）の最後にpyenv関連の設定を追記しましたか？ファイルの途中に書くと、後続の設定で上書きされてしまう可能性があります。

  • 解決策:

    • 使用するシェルの設定ファイル（通常は $HOME 直下の .bashrc または .zshrc）のみに、pyenvインストーラーが推奨する設定を正確に記述し、その他のファイルにある重複または競合する設定を削除またはコメントアウトしてください。
    • 設定ファイルを修正したら、必ず source <設定ファイル名> を実行するかターミナルを再起動してください。

8.4. シェル起動時に毎回 pyenv init - を実行する必要があるか

いいえ、通常は必要ありません。シェルの設定ファイル（.bashrc, .zshrc など）に eval "$(pyenv init -)" を一度追記しておけば、シェルが起動するたびに自動的に実行されます。

もし毎回手動で実行しないとpyenvが使えない場合、それはシェルの設定ファイルが正しく読み込まれていないか、そのファイルに上記の行が記述されていないかのどちらかです。

8.5. pyenv versions にシステムPythonが表示されない

通常 pyenv versions のリストには system が含まれます。これが表示されない場合、pyenvがシステムのデフォルトPythonを検出できていないか、PATH関連の問題が考えられます。

  • 確認ポイント:

    1. echo $PATH を実行し、~/.pyenv/shims や ~/.pyenv/bin より後に、システムPythonが含まれるディレクトリ（例: /usr/bin, /usr/local/bin など）が記述されているか確認してください。pyenvのshimパスが優先されるように設定されていることが前提ですが、system バージョンを検出するためにはシステムパスも参照できる必要があります。
    2. pyenv rehash を実行してみてください。これはshimを再生成するコマンドで、環境の変更後に実行が必要な場合があります。

  • 解決策:

    • PATH設定を確認し、pyenv関連のパスがシステムのデフォルトパスよりも前に来るように設定されていることを確認してください。
    • pyenv rehash を実行してください。

8.6. Windowsでの代替手段 (pyenv-win)

前述の通り、Windowsでは公式のpyenvは動作せず、代わりに pyenv-win が利用できます。pyenv-win はPowerShellやcmd.exeに対応しており、概ねpyenvと同様のコマンド体系（pyenv install, pyenv versions, pyenv global, pyenv local など）を提供しますが、内部実装やインストール方法が異なります。

WindowsでPythonバージョン管理を行いたい場合は、pyenv-winのGitHubページ を参照し、指示に従ってインストールしてください。インストールにはgitや7zipが必要となる場合があります。また、PATH設定の方法もUnix系とは異なります。

9. より高度な話題：pyenvの仕組み（shim）

pyenvがどのようにして複数のPythonバージョンを切り替えているのか、その核心にあるのが「shim（シム）」の仕組みです。

インストールセクションで触れたように、pyenvを初期化すると $PYENV_ROOT/shims (デフォルトでは ~/.pyenv/shims) というディレクトリがPATH環境変数に追加されます。このディレクトリは、システムPATHの他のほとんどのディレクトリよりも前に配置されます。

~/.pyenv/shims ディレクトリの中を見てみると、python, pip, python2, python3, pip2, pip3 など、よく使うPython関連の実行ファイルと同じ名前の実行可能ファイルが多数格納されていることがわかります。これらのファイルが「shim」です。

あなたがターミナルで python <script.py> のようにコマンドを実行すると、シェルのPATH設定の優先順位により、まず ~/.pyenv/shims/python というファイルが実行されます。

このshimファイルは非常にシンプルなラッパーです。実行されると、まずpyenvの内部ロジックを呼び出し、現在の環境（現在のディレクトリの .python-version ファイル、PYENV_VERSION 環境変数、グローバル設定ファイルなど）を調べて、どのPythonバージョンが現在アクティブであるべきか を判断します。

適切なPythonバージョン（例: Python 3.12.0）が特定されると、shimはそのバージョンの実際の実行ファイル（例: ~/.pyenv/versions/3.12.0/bin/python）に、渡された引数（例: <script.py>）を引き継いで処理をリダイレクトします。

つまり、あなたは常に同じパスにある ~/.pyenv/shims/python を実行しているのですが、その裏側ではpyenvが状況に応じて適切なバージョンのPython本体に処理を振り分けている、という仕組みです。

このshimの仕組みにより、

  • システムPATHに複数のPythonバージョンの bin ディレクトリを追加する必要がなくなり、PATH設定がシンプルになります。
  • シェルの環境変数（PYENV_VERSION）やファイル（.python-version, ~/.pyenv/version）を変更するだけで、動的に使用するPythonバージョンを切り替えることができます。
  • python, pip といったコマンド名を変えることなく、透過的にバージョン管理が行えます。

pyenvが提供する pyenv rehash コマンドは、このshimディレクトリを更新するために使用されます。新しいPythonバージョンをインストールしたり、pyenv virtualenv で新しい仮想環境を作成したりした後に実行することで、新しくインストールされたPythonや仮想環境に対応するshimファイルが ~/.pyenv/shims に生成され、pyenvがそれらを認識できるようになります。通常は pyenv install や pyenv virtualenv の実行時に自動的に pyenv rehash が行われるため、手動で実行する必要はあまりありませんが、バージョン切り替えがうまくいかない場合などに試してみる価値があります。

10. まとめ

本記事では、Python開発におけるバージョン管理の重要性と課題を説明し、それらを解決するツールであるpyenvについて、その仕組み、インストール、基本的な使い方、実践的な応用、仮想環境や他のツールとの連携、そしてトラブルシューティングに至るまで、幅広く解説しました。

pyenvを使うことで、

  • システムに影響を与えることなく、複数のPythonバージョンを同じ環境にインストールできます。
  • コマンド一つで、グローバル、プロジェクトごと、または一時的にPythonバージョンを簡単に切り替えられます。
  • プロジェクトごとに異なるPythonバージョンやパッケージ構成が必要な場合でも、クリーンで独立した開発環境を構築できます。
  • 仮想環境（venv, virtualenv, pyenv-virtualenv）と組み合わせることで、パッケージの依存関係問題を効果的に回避できます。
  • Poetryやpipenvなどのモダンな依存関係管理ツールとも組み合わせて、より洗練された開発ワークフローを構築できます。

pyenvは、Python開発者にとって必須とも言える強力なツールです。特に、複数のプロジェクトに関わる場合や、異なるPythonバージョンを使い分ける必要がある場合には、pyenvがもたらす効率性と快適さは計り知れません。

この記事を参考に、ぜひあなたの開発環境にpyenvを導入し、Pythonバージョン問題を解決してください。そして、さらに進んで仮想環境やPoetry、pipenvなどと組み合わせ、あなたにとって最適なPython開発環境を構築していきましょう。快適なPython開発ライフがあなたを待っています！

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール