【初心者向け】pyenvのインストールと基本的な使い方

By /

はい、承知いたしました。【初心者向け】pyenvのインストールと基本的な使い方に関する詳細な説明を含む記事を作成します。約5000語の要件を満たすため、各ステップや概念について丁寧に、具体例を交えながら解説します。

【初心者向け】Python開発の必需品！ pyenvで賢くPythonのバージョンを管理しよう

Pythonを使ってプログラミングや開発を始めた皆さん、こんにちは！

Pythonは非常に人気があり、Web開発、データ分析、機械学習、自動化スクリプトなど、さまざまな分野で活躍しています。しかし、Pythonを使い始めると、すぐに一つの壁にぶつかるかもしれません。それは、「Pythonのバージョン」に関する問題です。

「このプロジェクトはPython 3.8で開発されているのに、別のプロジェクトはPython 3.10じゃないと動かない！」
「チュートリアルで紹介されているライブラリが、なぜか自分の環境ではうまくインストールできない…もしかしてPythonのバージョンが違うせい？」
「新しいPythonバージョンをインストールしたら、今まで動いていたスクリプトが動かなくなった！」

こんな経験をしたことはありませんか？

Pythonの世界には、いくつかの異なるバージョン（例: Python 3.8, 3.9, 3.10, 3.11, 3.12…）が存在します。それぞれのバージョンには、新しい機能が追加されたり、古い機能が削除されたり、パフォーマンスが改善されたりといった違いがあります。プロジェクトによっては特定のバージョンを要求したり、使用しているライブラリが特定のバージョンにしか対応していなかったりすることもあります。

また、皆さんのコンピューターにも、OSが最初からインストールしているPython（「システムPython」と呼ばれることもあります）が存在するかもしれません。このシステムPythonはOSの動作に不可欠な場合があり、これを勝手にアップデートしたり、システムワイドにライブラリをインストールしたりすると、OSの動作がおかしくなるリスクがあります。

そこで登場するのが、Pythonのバージョンを管理するための強力なツール pyenv です！

この記事で学べること

この記事では、Python開発を始めたばかりの初心者の方に向けて、pyenvとは何か、なぜ必要なのか、そしてどのようにインストールして使うのかを、ステップバイステップで非常に詳しく解説します。

具体的には、以下の内容を学ぶことができます。

  • なぜPythonのバージョン管理が必要なのか
  • pyenvとはどんなツールなのか、そしてその仕組み
  • pyenvのインストール方法（macOS、Linux向け）
  • pyenvの基本的な使い方（バージョンのインストール、切り替え、アンインストールなど）
  • pyenvとPythonの仮想環境（venv/virtualenv）の関係と組み合わせ方
  • pyenv利用時のトラブルシューティング

この記事を読み終える頃には、複数のPythonバージョンを自在に操り、プロジェクトごとに最適な環境を構築できるようになっているはずです。さあ、pyenvの世界へ踏み出しましょう！

Pythonのバージョン管理、なぜ必要？

まずは、なぜPythonのバージョン管理が重要なのかをもう少し掘り下げてみましょう。

あなたがPythonでいくつかのプロジェクトに取り組んでいるとします。

  • プロジェクトA: Webフレームワーク「Django」を使っており、特定のライブラリの都合でPython 3.8で動作保証されている。
  • プロジェクトB: 最新の機械学習ライブラリ「TensorFlow」を使っており、Python 3.11以降で最高のパフォーマンスを発揮するとされている。
  • プロジェクトC: 会社のレガシーな内部ツールで、Python 3.6という少し古いバージョンで書かれている。

もし、あなたのコンピューターにPythonが一つだけインストールされている場合（例えばPython 3.12）、どうなるでしょうか？

プロジェクトAを動かそうとすると、Python 3.12では互換性の問題が発生するかもしれません。プロジェクトCはさらに古いバージョンなので、まったく動かない可能性もあります。プロジェクトBはPython 3.12で動くかもしれませんが、他のプロジェクトのためにダウングレードしたり、再びアップグレードしたりするたびに、全体の環境が不安定になるリスクがあります。

さらに、各プロジェクトは使用するライブラリとそのバージョンも異なります。プロジェクトAではDjango 3.xが必要でも、プロジェクトBではDjango 4.xが必要かもしれません。これらのライブラリをシステム全体のPython環境に一緒にインストールしようとすると、ライブラリ間の依存関係の衝突（あるライブラリは別のライブラリの古いバージョンを要求し、別のライブラリは新しいバージョンを要求するなど）が発生して、どちらかのプロジェクトが壊れてしまう可能性があります。

このように、複数のプロジェクトを並行して開発したり、メンテナンスしたりする場合、プロジェクトごとに異なるPythonバージョンやライブラリ環境が必要になることがよくあります。

システムに一つだけPythonをインストールしてすべてのプロジェクトで使い回す方法は、これらの問題を解決できません。

また、前述の通り、OSによってはシステムが利用するPythonがプレインストールされています。例えば、macOSや多くのLinuxディストリビューションには、システムの内部的なスクリプトを実行するためにPythonが標準でインストールされています。このシステムPythonを開発用途で直接使い、pip installなどでライブラリをシステム全体にインストールすると、システムが依存しているライブラリのバージョンが勝手に変わってしまい、OSの一部機能が動作しなくなるという深刻な問題を引き起こす可能性があります。これは絶対に避けるべきです。

これらの問題を解決するために、以下の2つのアプローチが重要になります。

  1. Pythonのバージョン管理: 複数のPythonバージョンをコンピューター上に共存させ、プロジェクトや作業内容に応じて簡単に切り替えられるようにする。
  2. 仮想環境（Virtual Environment）: プロジェクトごとに独立したライブラリインストール領域を作成し、ライブラリの依存関係の衝突を防ぐ。

pyenvは、この1番目の「Pythonのバージョン管理」を担うツールです。そして、多くのPython開発者は、pyenvを使って目的のPythonバージョンを準備し、さらにそのバージョンの上で仮想環境を作成して、ライブラリ管理を行っています。

pyenvとは

pyenvは、シンプルで非侵襲的なPythonバージョン管理ツールです。公式サイトでは “Simple Python Version Management” と紹介されています。

「非侵襲的 (non-intrusive)」というのは、システムにインストールされている既存のPython環境を壊したり変更したりすることなく、新しいPythonバージョンをユーザーのホームディレクトリなどの独立した場所にインストールし、管理できるという意味です。

pyenvを使うことで、以下のようなことが可能になります。

  • 複数のPythonバージョン（例: 2.7, 3.8, 3.9, 3.10, 3.11, 3.12, Anaconda, Minicondaなど）を同じコンピューターにインストールして共存させる。
  • コマンド一つで、どのPythonバージョンを使うかを簡単に切り替える。
  • プロジェクトのディレクトリに移動するだけで、自動的にそのプロジェクトで使うべきPythonバージョンに切り替わるように設定する。
  • システムにプリインストールされているPython環境を汚染することなく、開発環境を構築する。

pyenvの仕組み（ざっくり解説）

pyenvがどのようにしてPythonのバージョンを切り替えているのか、その仕組みを簡単に見てみましょう。

pyenvは、「shim（シム）」と呼ばれる仕組みを使っています。

  1. pyenvをインストールすると、~/.pyenv/shims というディレクトリが作成されます。このディレクトリには、python, pip, python3 のようなPython関連コマンドと同じ名前の小さなスクリプト（shim）がたくさん作成されます。
  2. pyenvの設定を行う際に、この ~/.pyenv/shims ディレクトリを、環境変数 PATH の一番先頭に追加します。PATH は、コマンドを実行したときにシェル（ターミナル）がどこから実行ファイルを探しに行くかを示すリストです。PATH の先頭にあるディレクトリが優先されます。
  3. あなたがターミナルで python とコマンドを実行すると、シェルは PATH の先頭から順番に python という名前のファイルを探します。すると、一番先頭に追加された ~/.pyenv/shims ディレクトリにある python shim が最初に見つかります。
  4. この python shim は、pyenvの本体 (pyenv) に制御を渡します。
  5. pyenvは、現在の環境設定（どのディレクトリにいるか、環境変数はどうなっているかなど）を見て、どのPythonバージョンを使うべきか を判断します。
  6. pyenvは、判断したバージョンの実際の python 実行ファイル（例えば ~/.pyenv/versions/3.10.12/bin/python）に、あなたが入力したコマンドや引数をそのまま渡して実行します。

つまり、pyenvは、あなたが実行する python や pip といったコマンドを一旦「横取り」して、適切なバージョンの実際のコマンドに「橋渡し」しているわけです。これにより、システム全体のPython環境には一切手を加えることなく、ユーザーごとに、あるいはプロジェクトごとに使うPythonバージョンを切り替えることができるのです。

この仕組みを理解しておくと、pyenvがなぜシステムに影響を与えないのか、なぜバージョンが切り替わるのかが分かりやすくなるでしょう。

pyenvと他のツールとの違い

Pythonのエコシステムには、バージョン管理や環境管理に関連するツールがいくつかあります。初心者が混同しやすい点を整理しておきましょう。

  • pyenv: Pythonのバージョンそのもの を管理するツール。複数のPythonバージョンをインストールし、切り替えることに特化しています。
  • venv / virtualenv: Pythonライブラリの依存関係 を管理するための仮想環境ツール。特定のPythonバージョンの中に、独立したライブラリのインストール領域を作成します。
  • pip: Pythonのパッケージ（ライブラリ） をインストール・管理するためのツール。

pyenvはvenv/virtualenvの代替ではありません。pyenvはまず「どのバージョンのPythonを使うか」を決定し、その上でvenv/virtualenvを使って「そのバージョンのPythonで使うライブラリ環境」を作る、というのが一般的な使い方です。両者は組み合わせて使うことで、より強力で柔軟な開発環境を構築できます。この連携についても後ほど詳しく解説します。

pyenvのインストール

それでは、実際にpyenvをインストールしてみましょう。インストール方法はOSによって少し異なります。ここでは、macOSとLinuxの一般的な方法を説明します。Windowsの場合は、pyenv-winという別のツールを使う必要がありますが、この記事ではmacOSとLinuxに絞って説明します。

インストールにおける重要な注意点:

  • 管理者権限は不要: pyenvは通常、ユーザーのホームディレクトリ以下にインストールされるため、sudo コマンドなどの管理者権限は必要ありません。
  • インターネット接続が必要: Pythonの各バージョンをダウンロードしてインストールするため、インターネットに接続できる環境が必要です。
  • ビルドツールが必要: Pythonの各バージョンはソースコードからコンパイル（ビルド）してインストールされます。そのため、コンパイラ（GCCなど）や開発に必要なライブラリ群がシステムにインストールされている必要があります。これがないと、Pythonのインストール時にエラーが発生します。

macOSへのインストール

macOSでは、パッケージマネージャーであるHomebrewを使う方法が最も簡単でおすすめです。Homebrewがインストールされていない場合は、先にHomebrewの公式サイトを参考にインストールしてください。

Homebrewを使う方法 (推奨)

  1. Homebrewを使ってpyenvをインストールします。

    ターミナルを開き、以下のコマンドを実行します。

    bash
    brew install pyenv

    このコマンドを実行すると、Homebrewがpyenv本体と、Pythonをソースコードからビルドするために必要な依存ライブラリのいくつか（OpenSSL, readline, zlibなど）を自動的にインストールしてくれます。これがHomebrewを使うメリットです。

  2. シェルの設定を行います。

    pyenvの仕組みを有効にするために、シェルの設定ファイル（.bash_profile, .bashrc, .zshrc など、使っているシェルによって異なります。macOS Catalina以降のデフォルトシェルはzshなので、通常は.zshrcです）に設定を追記する必要があります。

    以下のコマンドを実行して、pyenvに必要な設定を追記します。

    “`bash

    .zshrc を編集する場合 (macOS Catalina以降のデフォルトシェル)

    echo ‘eval “$(pyenv init -)”‘ >> ~/.zshrc

    bash を使っている場合

    echo ‘eval “$(pyenv init -)”‘ >> ~/.bash_profile’

    または、bashrc を使っている場合

    echo ‘eval “$(pyenv init -)”‘ >> ~/.bashrc’

    “`

    解説:
    * eval "$(pyenv init -)" は、pyenvの初期化を行うためのコマンドです。シェルの起動時に毎回このコマンドが実行されるように設定ファイルに追記します。この初期化によって、pyenvのshimが有効になり、PATH 環境変数が正しく設定されます。
    * >> ~/.zshrc は、コマンドの出力を標準出力ではなく、指定したファイル (~/.zshrc) の末尾に追記するという意味です。

  3. 設定を反映します。

    設定ファイルを編集しただけでは、現在開いているターミナルには設定は反映されません。以下のいずれかの方法で設定を反映させます。

    • ターミナルを一度閉じて、開き直す。

    • 以下のコマンドを実行して、設定ファイルを再読み込みする。

      “`bash

      .zshrc を編集した場合

      source ~/.zshrc

      .bash_profile または .bashrc を編集した場合

      source ~/.bash_profile

      または

      source ~/.bashrc

      “`

    source コマンドは、指定したファイルに書かれているコマンドを、現在のシェルセッションで実行するという意味です。

  4. pyenvが正しくインストールされたか確認します。

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

    bash
    pyenv --version

    もし command not found: pyenv のようなエラーが表示される場合は、シェルの設定が正しく行われていないか、設定の反映ができていない可能性があります。source コマンドを実行し直すか、ターミナルを再起動してみてください。

Gitを使う方法 (Homebrewを使わない場合)

Homebrewを使わない場合は、Gitを使ってpyenvのリポジトリをクローンし、手動で設定を行うことも可能です。

  1. pyenvをクローンします。

    ホームディレクトリに .pyenv という隠しディレクトリを作成し、その中にpyenvをクローンします。

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

  2. シェルの設定を行います。

    Homebrewを使った場合と同様に、シェルの設定ファイルに追記します。加えて、pyenvのインストール先を $PYENV_ROOT 環境変数で指定し、PATH 環境変数にpyenvの実行ファイルとshimsディレクトリを追加する必要があります。

    “`bash

    .zshrc を編集する場合

    echo ‘export PYENV_ROOT=”$HOME/.pyenv”‘ >> ~/.zshrc
    echo ‘export PATH=”$PYENV_ROOT/bin:$PATH”‘ >> ~/.zshrc
    echo ‘eval “$(pyenv init –path)”‘ >> ~/.zshrc # v1.2.0 以降はこちらが推奨
    echo ‘eval “$(pyenv init -)”‘ >> ~/.zshrc # これまでの方式（後方互換性あり）
    # 多くの場合はこれ一つでOKですが、
    # 上記2行（PYENV_ROOTとPATH）と init –path も
    # 記述しておくとより確実です。

    bash を使っている場合

    echo ‘export PYENV_ROOT=”$HOME/.pyenv”‘ >> ~/.bash_profile’

    echo ‘export PATH=”$PYENV_ROOT/bin:$PATH”‘ >> ~/.bash_profile’

    echo ‘eval “$(pyenv init –path)”‘ >> ~/.bash_profile’

    echo ‘eval “$(pyenv init -)”‘ >> ~/.bash_profile’

    etc… 使っているシェルに合わせてファイルを指定してください。

    “`

    解説:
    * export PYENV_ROOT="$HOME/.pyenv": pyenvのインストール先ディレクトリを PYENV_ROOT 環境変数に設定します。
    * export PATH="$PYENV_ROOT/bin:$PATH": pyenv コマンド自体が格納されている $PYENV_ROOT/bin ディレクトリを PATH の先頭に追加します。これにより、pyenv コマンドがどこからでも実行できるようになります。
    * eval "$(pyenv init -)": pyenvの初期化スクリプトを実行します。これにより、shimディレクトリ ($PYENV_ROOT/shims) が PATH の先頭に追加され、バージョン切り替えの仕組みが有効になります。

  3. 設定を反映します。

    Homebrewを使った場合と同様に、source コマンドを実行するか、ターミナルを再起動して設定を反映させます。

    bash
    source ~/.zshrc # または使っている設定ファイル

  4. 必要な依存ライブラリをインストールします。

    Homebrewを使った場合は自動でインストールされますが、Gitで手動インストールした場合は、Pythonをビルドするために必要な依存ライブラリを自分でインストールする必要があります。

    macOSの場合、これらは通常Xcode Command Line Toolsに含まれています。インストールされていない場合は、以下のコマンドでインストールできます。

    bash
    xcode-select --install

    他にも、OpenSSL、readline、zlibなどのライブラリが必要になる場合があります。Homebrewでインストールしておくと便利です。

    bash
    brew install openssl readline zlib

    これらのライブラリがないと、後で pyenv install コマンドでPythonをインストールしようとしたときにビルドエラーが発生する可能性が高いです。

  5. pyenvが正しくインストールされたか確認します。

    bash
    pyenv --version

    バージョンが表示されれば成功です。

Linuxへのインストール

Linuxの場合も、Gitを使ってpyenvをクローンし、シェルの設定を行うのが一般的な方法です。加えて、macOS以上にPythonのビルドに必要な依存ライブラリを自分でインストールする必要があります。

  1. 必要な依存ライブラリをインストールします。

    これは非常に重要なステップです。Pythonをソースコードからビルドするためには、コンパイラや様々な開発用ライブラリが必要です。ディストリビューションによって必要なパッケージの名前やインストールコマンドが異なります。以下に主要なディストリビューションでの例を示します。

    • Debian/Ubuntu系: apt コマンドを使います。

      bash
      sudo apt update
      sudo apt install -y make 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

      解説:
      * sudo apt update: パッケージリストを最新の状態に更新します。
      * sudo apt install -y ...: 必要なパッケージをインストールします。 -y オプションは、インストール時の確認プロンプトに自動的に「はい」と答えるオプションです。
      * make, build-essential: ビルドに必要な基本的なツールチェーン（コンパイラ、リンカなど）。
      * libssl-dev, zlib1g-dev, libbz2-dev, libreadline-dev, libsqlite3-dev, libncursesw5-dev, tk-dev, libffi-dev, liblzma-dev: Pythonの様々な機能（SSL通信、圧縮/解凍、readlineによるコマンド履歴、SQLiteデータベース、cursesによるターミナルUI、TkinterによるGUI、外部関数インターフェース、LZMA圧縮など）を有効にするために必要な開発用ライブラリ。
      * wget, curl: ファイルダウンロードコマンド。
      * llvm, xz-utils, libxml2-dev, libxmlsec1-dev: その他の依存ライブラリ。

    • Fedora/CentOS/RHEL系: dnf または yum コマンドを使います。

      “`bash
      sudo dnf update # Fedoraの場合

      または

      sudo yum update # CentOS/RHELの場合

      sudo dnf install -y git zlib-devel bzip2-devel readline-devel sqlite-devel \
      openssl-devel tk-devel libffi-devel xz-devel \
      gcc make patch
      “`

      解説:
      * sudo dnf update / sudo yum update: パッケージリストを最新の状態に更新します。
      * sudo dnf install -y ... / sudo yum install -y ...: 必要なパッケージをインストールします。
      * パッケージ名がDebian/Ubuntu系と少し異なります（例: zlib-devel vs zlib1g-dev）。役割はほぼ同じです。
      * git, gcc, make, patch: pyenvやPythonのビルドに必要な基本的なツール。

    もし特定のOSやディストリビューションを使っている場合は、pyenv install --list の出力で特定のバージョン（例: 3.10.12）を選択し、pyenv install 3.10.12 を試してみるのが良いでしょう。もし依存ライブラリが不足している場合は、エラーメッセージで不足しているライブラリについてヒントが得られることがあります。

  2. pyenvをクローンします。

    macOSのGitを使った方法と同様に、ホームディレクトリにクローンします。

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

  3. シェルの設定を行います。

    macOSのGitを使った方法と同様に、シェルの設定ファイル（通常は.bashrc または .profile ですが、使っているシェルによって異なります）に設定を追記します。

    “`bash

    .bashrc または .profile を編集する場合

    echo ‘export PYENV_ROOT=”$HOME/.pyenv”‘ >> ~/.bashrc # または ~/.profile
    echo ‘export PATH=”$PYENV_ROOT/bin:$PATH”‘ >> ~/.bashrc # または ~/.profile
    echo ‘eval “$(pyenv init –path)”‘ >> ~/.bashrc # または ~/.profile # v1.2.0 以降推奨
    echo ‘eval “$(pyenv init -)”‘ >> ~/.bashrc # または ~/.profile # これまでの方式
    # 通常は init – だけでOKですが、
    # 上記2行（PYENV_ROOTとPATH）と init –path も
    # 記述しておくとより確実です。

    .zshrc を使っている場合 (最近のLinuxディストリビューションでzshをデフォルトにする場合もあり)

    echo ‘export PYENV_ROOT=”$HOME/.pyenv”‘ >> ~/.zshrc

    echo ‘export PATH=”$PYENV_ROOT/bin:$PATH”‘ >> ~/.zshrc

    echo ‘eval “$(pyenv init –path)”‘ >> ~/.zshrc

    echo ‘eval “$(pyenv init -)”‘ >> ~/.zshrc

    “`

    解説: macOSのGitを使った場合と同様です。PYENV_ROOT と PATH の設定、そして eval "$(pyenv init -)" による初期化が必要です。

  4. 設定を反映します。

    macOSの場合と同様に、source コマンドを実行するか、ターミナルを再起動して設定を反映させます。

    bash
    source ~/.bashrc # または使っている設定ファイル

  5. pyenvが正しくインストールされたか確認します。

    bash
    pyenv --version

    バージョンが表示されれば成功です。

これでpyenv本体のインストールと基本設定は完了です！

pyenvの基本的な使い方

pyenvのインストールが完了したら、いよいよPythonのバージョンをインストールして使ってみましょう。

基本的な使い方をマスターすれば、プロジェクトごとにPython環境を簡単に切り替えられるようになります。

1. 利用可能なPythonバージョンの確認

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

bash
pyenv install --list

このコマンドを実行すると、インストール可能なPythonバージョンがずらっとリストアップされます。

text
Available versions:
2.1.3
2.2.3
2.3.7
... (たくさんの古いバージョン) ...
3.7.16
3.8.16
3.9.16
3.10.11
3.11.3
3.12.0
anaconda-2.0.1
anaconda3-2023.03
... (AnacondaやMinicondaなどの配布版) ...
miniconda-latest
miniconda3-latest
... (jython, pypyなどの代替実装) ...
pypy3.9-7.3.11
pypy3.10-7.3.11

リストには、公式のCPython（いわゆる「普通の」Python）だけでなく、AnacondaやMinicondaといったデータ科学向けのPython配布版、PyPy（高速実行に特化したPython実装）、Jython（JavaVM上で動作するPython）なども含まれています。

ヒント: リストが長すぎる場合は、grep コマンドと組み合わせて特定のバージョンだけを絞り込むことができます。例えば、Python 3.10系だけを探したい場合は以下のようになります。

bash
pyenv install --list | grep 3.10

2. Pythonのインストール

インストールしたいPythonバージョンが決まったら、pyenv install <バージョン名> コマンドでインストールします。バージョン名は、pyenv install --list で表示されたものを使います。

例えば、Python 3.10.12をインストールしたい場合：

bash
pyenv install 3.10.12

このコマンドを実行すると、pyenvは指定されたバージョンのPythonのソースコードをダウンロードし、コンパイルしてインストールします。インストール先は、通常 ~/.pyenv/versions/<バージョン名> のようになります。

インストールには時間がかかります！
Pythonのビルドは、コンピューターの性能によっては数分から数十分かかることがあります。気長に待ちましょう。
また、インストール中にエラーが発生した場合、最も可能性が高い原因は「必要な依存ライブラリが不足している」ことです。ターミナルに表示されるエラーメッセージをよく確認し、必要に応じて「pyenvのインストール」セクションに戻って依存ライブラリのインストールを試してみてください。

インストール時のオプション

  • --verbose: ビルドの詳細なログを表示します。エラーが発生した際に原因を特定するのに役立ちます。
  • --keep: ビルド中に作成された一時ファイルを削除せず残します。デバッグ目的で使われます。

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

現在pyenvで管理されている、インストール済みのPythonバージョンを確認するには、pyenv versions コマンドを使います。

bash
pyenv versions

実行結果の例：

text
system
* 3.10.12 (set by /home/user/.pyenv/version)
3.11.3

解説:
* system: これはシステムに元々インストールされているPythonを指します。pyenvが管理するバージョンの一つとして扱われます。
* 3.10.12: pyenvを使ってインストールしたPythonのバージョンです。
* 3.11.3: pyenvを使ってインストールした別のバージョンです。
* 行の先頭にある * (アスタリスク) は、現在アクティブになっている（使われている）Pythonバージョン を示します。上の例では、Python 3.10.12がアクティブになっています。
* 括弧内の “(set by …)” は、そのバージョンがどのようにしてアクティブになったかを示しています。例では /home/user/.pyenv/version というファイルによって設定されています。

pyenv version (複数形ではない) コマンドは、現在アクティブになっているバージョンだけをシンプルに表示します。

bash
pyenv version

text
3.10.12 (set by /home/user/.pyenv/version)

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

pyenvの最も重要な機能は、Pythonバージョンの切り替えです。pyenvには、バージョンを切り替えるための方法がいくつかあります。それぞれ影響範囲が異なります。

  • global: システム全体（ただし、後述の local や shell 設定がない場所）でデフォルトとして使用するバージョンを設定します。
  • local: 特定のディレクトリ（主にプロジェクトディレクトリ）とそのサブディレクトリ内でのみ使用するバージョンを設定します。
  • shell: 現在開いているシェルのセッション内でのみ使用するバージョンを設定します。

pyenvは、これらの設定を以下の優先順位で評価し、最終的にどのPythonバージョンを使うかを決定します。

shell > local > global > system

つまり、shell 設定が最も優先度が高く、もし shell 設定がなければ local 設定を見にいく、という流れです。

a. global バージョンの設定

pyenv global <バージョン名> コマンドは、特に local や shell 設定がない場合にデフォルトで使用されるPythonバージョンを設定します。

“`bash

Python 3.10.12 をデフォルトバージョンにする例

pyenv global 3.10.12
“`

このコマンドを実行すると、~/.pyenv/version というファイルが作成（または更新）され、その中に指定したバージョン名が書き込まれます。

pyenv versions を実行すると、3.10.12 の行に * が移動していることを確認できます。

bash
pyenv versions

text
system
* 3.10.12 (set by /home/user/.pyenv/version)
3.11.3

これで、他の設定がない場所では、python コマンドを実行すると Python 3.10.12 が使われるようになります。

システムに元々インストールされているPythonに戻したい場合は、pyenv global system とします。

bash
pyenv global system

bash
pyenv versions

text
* system (set by /home/user/.pyenv/version)
3.10.12
3.11.3

b. local バージョンの設定

pyenv local <バージョン名> コマンドは、現在いるディレクトリとそのサブディレクトリ内で使用するPythonバージョンを設定します。これは、プロジェクトごとに異なるPythonバージョンを使いたい場合に非常に便利です。

プロジェクトディレクトリに移動して、そのディレクトリ専用のバージョンを設定してみましょう。

“`bash

プロジェクトディレクトリを作成（すでにある場合は移動）

mkdir my_project
cd my_project

このプロジェクトでは Python 3.11.3 を使いたいと設定

pyenv local 3.11.3
“`

このコマンドを実行すると、現在いるディレクトリ (my_project) の中に .python-version というファイルが作成され、その中に指定したバージョン名 (3.11.3) が書き込まれます。

このディレクトリ内で pyenv versions を実行すると、3.11.3 の行に * が表示されます。

bash
pyenv versions

text
system
3.10.12
* 3.11.3 (set by /home/user/my_project/.python-version)

また、このディレクトリ内で python --version や python -V を実行すると、Python 3.11.3 が使われていることが確認できます。

bash
python --version

text
Python 3.11.3

一つ上のディレクトリ (cd .. で my_project の外に出る) に移動して pyenv versions を実行すると、.python-version ファイルがないため、global設定のバージョン（またはsystem）がアクティブになっていることが確認できます。

bash
cd ..
pyenv versions

text
system
* 3.10.12 (set by /home/user/.pyenv/version) # local設定がないのでglobal設定が有効
3.11.3

このように、pyenv local で設定しておけば、そのプロジェクトディレクトリに移動するだけで、自動的に正しいPythonバージョンが選択されるようになります。これは非常に強力な機能です。

.python-version ファイルはバージョン管理システム（Gitなど）で管理するのが一般的です。そうすることで、プロジェクトに参加する他の開発者も、リポジトリをクローンして pyenv がインストールされていれば、自動的に適切なPythonバージョンで開発できるようになります。（ただし、そのバージョンがインストールされている必要はあります）

local設定を解除したい場合は、設定したディレクトリで pyenv local --unset コマンドを実行します。.python-version ファイルが削除されます。

bash
pyenv local --unset

c. shell バージョンの設定

pyenv shell <バージョン名> コマンドは、現在開いているターミナルセッション内でのみ使用するPythonバージョンを設定します。

これは一時的に特定のバージョンを試したい場合などに便利です。

“`bash

現在のターミナルセッション内だけ Python 3.11.3 を使う

pyenv shell 3.11.3
“`

このコマンドを実行してもファイルは作成されません。設定は現在のシェルの環境変数（PYENV_VERSION）にのみ影響します。

pyenv versions を実行すると、3.11.3 の行に * が表示され、(set by PYENV_VERSION) と表示されるはずです。

bash
pyenv versions

text
system
3.10.12
* 3.11.3 (set by PYENV_VERSION)

この設定は、そのターミナルセッションを閉じるか、pyenv shell --unset コマンドを実行するまで有効です。

bash
pyenv shell --unset

bash
pyenv versions

text
system
* 3.10.12 (set by /home/user/.pyenv/version) # shell設定が解除されたのでlocalまたはglobal設定に戻る
3.11.3

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

不要になったPythonバージョンは、pyenv uninstall <バージョン名> コマンドでアンインストールできます。

インストール済みのバージョンは pyenv versions で確認できます。

bash
pyenv versions

text
system
* 3.10.12 (set by /home/user/.pyenv/version)
3.11.3

例えば、Python 3.11.3 をアンインストールしたい場合：

bash
pyenv uninstall 3.11.3

確認メッセージが表示されるので、y と入力してEnterキーを押すとアンインストールが実行されます。

text
pyenv: Uninstalling 3.11.3...

注意点: 現在アクティブになっているバージョンはアンインストールできません。もしアクティブなバージョンをアンインストールしたい場合は、先に pyenv global や pyenv local などで別のバージョンに切り替えてからアンインストールしてください。

pyenvと仮想環境（venv/virtualenv）の組み合わせ

ここまでで、pyenvを使ってPythonのバージョンを管理できるようになりました。しかし、Python開発で本当に強力なのは、pyenvによる「バージョン管理」と、venv/virtualenvによる「仮想環境（ライブラリ管理）」を組み合わせて使うことです。

なぜ組み合わせる必要があるのか？

pyenvはあくまでPythonの実行ファイルそのもの（例えば /path/to/python3.10）を切り替えるツールです。pip install でライブラリをインストールした場合、そのライブラリは現在アクティブになっているバージョンのPythonのサイトパッケージディレクトリにインストールされます。

もし pyenv だけでバージョンを切り替えながら開発していると、以下のような問題が発生します。

  • ライブラリの衝突: プロジェクトAでライブラリXのバージョン1をインストールし、プロジェクトBでライブラリXのバージョン2をインストールしたい場合、同じPythonバージョンを使っているとどちらか一方しかインストールできません。バージョンを切り替えても、インストール先のディレクトリは同じバージョンのPython内になるため、結局ライブラリ環境がごちゃ混ぜになってしまいます。
  • 環境の再現性: プロジェクトが必要とするライブラリとその正確なバージョンを管理するのが難しくなります。開発環境を他の人に共有したり、本番環境にデプロイしたりする際に、必要なライブラリを正確に再現するのが困難になります。

これらの問題を解決するのが「仮想環境」です。仮想環境は、特定のPythonバージョンの中に、独立したライブラリインストール領域を作成します。プロジェクトごとに仮想環境を作成し、その仮想環境の中に必要なライブラリだけをインストールすることで、他のプロジェクトやシステムのPython環境に影響を与えず、プロジェクト固有のクリーンなライブラリ環境を構築できます。

Python 3.3以降には、標準ライブラリとして venv という仮想環境作成ツールが含まれています。Python 2系や古いPython 3系、またはより多機能な仮想環境が必要な場合は、外部ライブラリである virtualenv を使うこともあります。

一般的なワークフロー

pyenvと仮想環境を組み合わせた開発ワークフローは以下のようになります。

  1. pyenvで、プロジェクトに必要なPythonバージョンをインストールする。
    例: pyenv install 3.10.12
  2. インストールした特定のPythonバージョンを使って、プロジェクトディレクトリ内に仮想環境を作成する。
    例: python -m venv .venv
  3. 作成した仮想環境を有効化する。
    例: source .venv/bin/activate
  4. 仮想環境が有効な状態で、プロジェクトに必要なライブラリを pip install する。
    例: pip install Django requests
  5. プロジェクトでの作業が終わったら、仮想環境を無効化する。
    例: deactivate

pyenvで特定のPythonバージョンを使って仮想環境を作成する方法

まず、プロジェクトディレクトリに移動します。

bash
cd path/to/your/project

次に、pyenv local コマンドを使って、このプロジェクトで使用したいPythonバージョンを設定します。ここでは例として Python 3.10.12 を使います。もしインストールされていなければ pyenv install 3.10.12 で先にインストールしておいてください。

bash
pyenv local 3.10.12

これで、このディレクトリ内では python コマンドが Python 3.10.12 を指すようになります。確認してみましょう。

bash
python --version

text
Python 3.10.12

この Python 3.10.12 を使って仮想環境を作成します。Python 3.3以降であれば、標準ライブラリの venv を使えます。仮想環境の名前は慣習的に .venv とすることが多いです。

bash
python -m venv .venv

解説:
* python: 現在アクティブな（pyenvで設定した）Pythonの実行ファイルを指します。
* -m venv: Pythonの venv モジュールを実行するという意味です。
* .venv: 作成する仮想環境のディレクトリ名を指定します。カレントディレクトリに .venv というディレクトリが作成され、その中にPythonの実行ファイルのコピーやライブラリインストール用のディレクトリなどが配置されます。

仮想環境が作成されたら、それを有効化します。

bash
source .venv/bin/activate

コマンドプロンプトの先頭に (.venv) のような仮想環境の名前が表示されれば成功です。（表示内容はシェルの設定によります）

text
(.venv) $

この (.venv) は、現在仮想環境が有効化されていることを示しています。

この状態で python や pip コマンドを実行すると、作成した仮想環境内のものが使われます。

“`bash

仮想環境内のPythonバージョンを確認（pyenv localで設定したバージョンと同じはず）

which python

出力例: /path/to/your/project/.venv/bin/python

仮想環境内のpipでライブラリをインストール

pip install requests

requests ライブラリが .venv/lib/pythonX.Y/site-packages/ にインストールされる

“`

プロジェクトに必要なライブラリをすべてインストールしたら、インストールしたライブラリのリストを requirements.txt ファイルに書き出しておくと、環境を共有したり再現したりするのに役立ちます。

bash
pip freeze > requirements.txt

他の人がこのプロジェクトをセットアップする際は、リポジトリをクローンし、pyenv local で同じPythonバージョンを設定し、仮想環境を作成・有効化した後、以下のコマンドで必要なライブラリを一括でインストールできます。

bash
pip install -r requirements.txt

プロジェクトでの作業を終える際は、以下のコマンドで仮想環境を無効化します。

bash
deactivate

コマンドプロンプトから (.venv) が消え、pyenvのglobalまたはlocal設定のPython環境に戻ります。

pyenv-virtualenv プラグイン (発展)

pyenvには、仮想環境の作成と管理をより簡単に統合するためのプラグイン pyenv-virtualenv があります。これは必須ではありませんが、知っておくと便利です。

pyenv-virtualenv を使うと、pyenv virtualenv <Pythonバージョン> <仮想環境名> のようなコマンドで、特定のPythonバージョンに基づいた仮想環境を作成し、pyenv activate <仮想環境名> で有効化、pyenv deactivate で無効化できるようになります。さらに、pyenv local <仮想環境名> と設定することで、そのディレクトリに移動するだけで自動的に仮想環境が有効化されるようにすることも可能です。

Homebrewでpyenvをインストールした場合、pyenv-virtualenv も一緒にインストールされることがあります。Gitで手動インストールした場合は、別途クローンして設定する必要があります。

“`bash

pyenv-virtualenv のインストール例 (Gitの場合)

git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv

シェル設定への追記 (通常、pyenv init の前に記述)

echo ‘eval “$(pyenv virtualenv-init -)”‘ >> ~/.zshrc # または使っている設定ファイル
“`

設定を反映させた後、使い方は以下のようになります。

“`bash

Python 3.10.12 に基づく仮想環境 ‘my_project_venv’ を作成

pyenv virtualenv 3.10.12 my_project_venv

作成された仮想環境を確認

pyenv versions

出力例:

system

3.10.12

* 3.10.12/envs/my_project_venv

3.11.3

my_project_venv -> 3.10.12/envs/my_project_venv

仮想環境を有効化

pyenv activate my_project_venv

仮想環境を無効化

pyenv deactivate

ディレクトリに移動した際に自動で有効化されるように設定

cd path/to/your/project
pyenv local my_project_venv # これで .python-version ファイルに仮想環境名が書き込まれる

仮想環境のアンインストール

pyenv uninstall my_project_venv
“`

pyenv-virtualenv を使うと、pyenvのバージョン管理と仮想環境の有効化/無効化の操作が統一されて少し楽になります。どちらの方法を使うかは好みに応じて選べます。標準の venv と手動でのactivate/deactivateでも全く問題ありません。

トラブルシューティング

pyenvを使っていると、特にインストール時や設定時にいくつか問題に遭遇することがあります。ここでは、よくある問題とその対処法をいくつか紹介します。

1. pyenv コマンドが見つからない (command not found: pyenv)

原因: シェルの PATH 環境変数にpyenvの実行ファイルがあるディレクトリ ($PYENV_ROOT/bin) やshimディレクトリ ($PYENV_ROOT/shims) が含まれていないか、設定変更が反映されていない。

対処法:

  • シェルの設定ファイルを確認する: .bashrc, .zshrc, .bash_profile, .profile など、使用しているシェルの設定ファイルに export PYENV_ROOT=..., export PATH=..., eval "$(pyenv init -)" （または eval "$(pyenv init --path)" と eval "$(pyenv init -)" の両方）が正しく追記されているか確認します。特に $HOME/.pyenv が存在することを確認してください。
  • 設定を反映させる: 設定ファイルを編集した場合、現在のターミナルセッションに反映させるために source <設定ファイル名> コマンドを実行するか、ターミナルを一度閉じて開き直してください。
    例: source ~/.zshrc
  • typoを確認: コマンド名やファイル名に誤字脱字がないか確認します。

2. pyenv install <バージョン> でPythonのビルドに失敗する

原因: Pythonをソースコードからビルドするために必要な依存ライブラリが不足していることが最も多い原因です。OSやディストリビューションによって必要なライブラリは異なります。

対処法:

  • エラーメッセージをよく読む: ビルドログの最後に表示されるエラーメッセージに、不足しているライブラリの名前やエラーの種類に関するヒントが含まれていることが多いです。
  • 必要な依存ライブラリをインストールする: 本記事の「pyenvのインストール」セクションを参照し、使用しているOS/ディストリビューションに対応した必要な依存ライブラリ（build-essential, libssl-dev, zlib1g-dev, readline-develなど）をインストールします。sudo apt install ... や sudo dnf install ... のコマンドを再確認してください。
  • macOSの場合: Xcode Command Line Tools がインストールされているか確認してください (xcode-select --install)。また、Homebrewで openssl, readline, zlib などがインストールされているか確認してください (brew install openssl readline zlib)。
  • 古いバージョンを試す: 特定のバージョンでビルドの問題が発生する場合は、別のバージョンのPythonを試してみるか、そのバージョンに関する既知の問題を検索してみるのも良いでしょう。

3. Pythonバージョンが切り替わらない、あるいは意図しないバージョンが使われる

原因: pyenvのバージョン切り替えの優先順位の理解不足、または .python-version ファイルの場所や内容の誤り。

対処法:

  • pyenv versions を実行する: 現在アクティブになっているバージョンと、それがどのように設定されているか（set by …）を確認します。
  • .python-version ファイルの場所を確認する: プロジェクトディレクトリで pyenv local <バージョン> を実行した場合、カレントディレクトリに .python-version ファイルが作成されます。そのファイルが意図したディレクトリに存在するか、内容が正しいか確認してください。もし親ディレクトリに .python-version ファイルがある場合、そちらの設定が優先される可能性があります（ただし、通常は一番近いディレクトリの設定が優先されます）。
  • pyenv version を実行する: 現在有効なバージョンと設定元をシンプルに確認できます。
  • shell 設定を確認する: pyenv shell で一時的な設定がされている場合、それが最優先されます。意図しない場合は pyenv shell --unset で解除してください。
  • PATH 環境変数を確認する: echo $PATH コマンドで、$PYENV_ROOT/shims が他のPython実行パスよりも前に来ているか確認してください。eval "$(pyenv init -)" が正しく実行されていない可能性があります。
  • シェルの再起動: 設定変更を確実にするために、ターミナルを一度閉じて開き直してみるのも有効です。

4. pip install したはずのパッケージがインポートできない

原因: パッケージをインストールした仮想環境やPythonバージョンと、現在スクリプトを実行しようとしているPython環境が異なる。

対処法:

  • 現在アクティブなPython環境を確認する:
    • pyenv versions: 現在アクティブなpyenvバージョンを確認。
    • which python: 実行される python コマンドのパスを確認。仮想環境が有効であれば、仮想環境内のパス (/path/to/project/.venv/bin/python など) になっているはずです。
    • which pip: 実行される pip コマンドのパスを確認。仮想環境が有効であれば、仮想環境内のパスになっているはずです。
  • 仮想環境が有効になっているか確認する: コマンドプロンプトの表示を確認するか、source .venv/bin/activate コマンドを再度実行して仮想環境を有効化してください。（pyenv-virtualenv を使っている場合は pyenv activate <仮想環境名>)
  • パッケージが正しくインストールされているか確認する: 仮想環境が有効な状態で pip list コマンドを実行し、目的のパッケージがリストに含まれているか確認してください。
  • 複数のターミナルを使っている場合: 各ターミナルセッションは独立した環境を持ちます。別のターミナルで作業している場合は、そちらでも適切なPythonバージョンと仮想環境が有効になっているか確認が必要です。

5. macOSでmacportsやHomebrewでインストールしたPythonと衝突する

原因: pyenvよりも前に、これらのパッケージマネージャーでインストールされたPythonのパスが PATH 環境変数に含まれており、そちらが優先されている。

対処法:

  • PATH 環境変数の順序を修正する: シェルの設定ファイル (.bashrc, .zshrc など) を開き、pyenv の設定 (export PYENV_ROOT=..., export PATH="$PYENV_ROOT/bin:$PATH", eval "$(pyenv init -)") が、macportsやHomebrewでインストールされたPythonのパス (/opt/local/bin, /usr/local/bin など) を PATH に追加する行よりも後に記述されていることを確認してください。これにより、pyenvのshimディレクトリが優先されるようになります。
  • 設定ファイルを修正したら source <設定ファイル名> で反映させるか、ターミナルを再起動します。

トラブルシューティングは、エラーメッセージを丁寧に読み、現在の環境設定（どのバージョンが有効か、PATHはどうなっているかなど）を確認することが重要です。

発展的な使い方 (簡単な紹介)

pyenvには、さらに便利な機能や関連ツールがあります。いくつか簡単に紹介します。

  • pyenv update: pyenv自体を最新バージョンにアップデートします。Homebrewでインストールした場合は brew upgrade pyenv を使います。Gitで手動インストールした場合は、pyenvディレクトリ内で git pull を実行し、必要に応じて pyenv init を再評価します。

    “`bash

    Homebrewの場合

    brew update
    brew upgrade pyenv

    Gitの場合

    cd $(pyenv root)
    git pull
    exec $SHELL # シェルを再起動して設定を反映
    “`

  • pyenv-virtualenv: 前述の通り、pyenvでの仮想環境管理を統合するプラグインです。pyenv virtualenv, pyenv activate, pyenv deactivate コマンドを使えるようになります。

  • pyenv-which-ext: pyenv which <コマンド名> コマンドで、指定したコマンド（例えば python や pip）が、pyenvのどのバージョンディレクトリにある実際のファイルに対応しているかを確認できるようになるプラグインです。トラブルシューティング時に便利です。

    “`bash
    pyenv which python

    出力例: /home/user/.pyenv/versions/3.10.12/bin/python

    “`

これらのプラグインは、GitHubのpyenv組織（https://github.com/pyenv）で確認できます。

まとめ

この記事では、Python開発におけるバージョン管理の重要性と、それを実現するための強力なツールであるpyenvについて、そのインストール方法から基本的な使い方、そして仮想環境との組み合わせ方までを詳しく解説しました。

  • 複数のプロジェクトで異なるPythonバージョンが必要な場合や、システムのPython環境を汚染したくない場合に、pyenvは非常に役立ちます。
  • pyenvは、shimという仕組みを使ってコマンドを横取りし、どのバージョンのPythonを使うべきかを賢く判断します。
  • pyenvのインストールは、macOSではHomebrewを使うのが最も簡単ですが、Gitによる手動インストールも可能です。LinuxではGitによる手動インストールが一般的で、OSに応じた依存ライブラリのインストールが重要です。
  • インストール後は、シェルの設定ファイル（.bashrc, .zshrc など）に eval "$(pyenv init -)" などの設定を追記し、設定を反映させる必要があります。
  • pyenv install --list でインストール可能なバージョンを確認し、pyenv install <バージョン> でPythonをインストールします。
  • pyenv versions でインストール済みのバージョンを確認し、* で現在アクティブなバージョンを特定します。
  • バージョンの切り替えは、pyenv global <バージョン> (デフォルト)、pyenv local <バージョン> (ディレクトリごと)、pyenv shell <バージョン> (一時的) の3つの方法があります。優先順位は shell > local > global です。
  • Python開発においては、pyenvで適切なPythonバージョンを用意した上で、venv や virtualenv を使ってプロジェクトごとの仮想環境を作成し、ライブラリを管理するのがベストプラクティスです。
  • インストールや使用中に問題が発生した場合は、エラーメッセージをよく確認し、依存ライブラリやシェルの設定、PATH 環境変数、.python-version ファイルなどを確認してトラブルシューティングを行いましょう。

pyenvと仮想環境を組み合わせることで、あなたはもうPythonのバージョンやライブラリの依存関係に悩まされることなく、それぞれのプロジェクトに集中して開発を進めることができるようになります。

この記事が、皆さんのPython学習や開発の助けになれば幸いです。まずは、この記事を参考にpyenvをインストールし、いくつかのPythonバージョンを試してみてください。そして、ぜひあなたのプロジェクトでpyenvと仮想環境を活用してみてください。

Happy Coding!

コメントする

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

上部へスクロール