閉じる

現場で使えるpyenv入門｜Pythonバージョン管理と環境構築を一気に理解

広告

Pythonはバージョンによる仕様差分や依存ライブラリの要件がシビアな言語です。

そのため、現場の開発では「どのプロジェクトで、どのPythonを、どの依存関係で使うか」を正しく管理できているかどうかが、トラブルを減らすポイントになります。

本記事では、Pythonバージョン管理ツールであるpyenvと、その周辺ツール(pyenv-virtualenvなど)を用いて、実務レベルで使える環境構築と運用方法を体系的に解説します。

目次 [ close ]
  1. pyenvとは｜Pythonバージョン管理の基本
    1. pyenvでできることと導入するメリット
    2. pyenv-virtualenvとの違いと役割分担
    3. 他のPythonバージョン管理ツールとの比較
  2. 現場で使えるpyenvのインストールと初期設定
    1. macOSでのpyenvインストール手順
    2. Linux(Ubuntu)でのpyenvインストール手順
    3. Windowsでのpyenv利用(pyenv-win)のポイント
    4. シェル設定(zsh・bash)へのpyenvの組み込み
    5. python-buildの導入とビルドに必要なライブラリ
  3. 実務で役立つpyenvの基本操作と使い分け
    1. pyenvでインストール可能なPythonバージョンの確認
    2. pyenv installでPythonをインストールする手順
    3. global・local・shellでPythonバージョンを切り替える
    4. プロジェクトごとにPythonバージョンを固定する
    5. システムPythonとの共存と注意点
    6. 既存プロジェクトにpyenvを導入する手順
  4. pyenvと仮想環境(virtualenv)による開発環境構築
    1. pyenv-virtualenvで仮想環境を作成・切り替え
    2. プロジェクトフォルダと仮想環境の紐付け
    3. requirements.txtとpipで依存関係を管理する
    4. VSCodeなどIDEでpyenv環境を認識させる設定
    5. チーム開発でのpyenv活用
  5. まとめ

pyenvとは｜Pythonバージョン管理の基本

pyenvでできることと導入するメリット

pyenvは、1つのマシン上に複数のPythonバージョンを共存させ、プロジェクトごとに使うバージョンを切り替えるためのツールです。

OS標準のPythonに手を加えることなく、任意のバージョンをユーザー領域にインストールし、簡単に切り替えられるようにしてくれます。

pyenvでできる主なこと

文章で整理すると、pyenvが提供してくれる主な機能は次のようになります。

まず、異なるPythonバージョンをインストールできます。

たとえばPython 3.7、3.8、3.11を同じマシンにインストールし、いつでも切り替えられます。

また、グローバルのデフォルトバージョンを決めたり、ディレクトリ単位(プロジェクト単位)で使用するバージョンを固定したりできます。

さらに、シェルの一時的なセッションだけ別バージョンに切り替える、といった使い方も可能です。

環境変数PATHを自動的に書き換え、「どのpythonコマンドが実行されるか」を透過的に制御してくれる点も特徴です。

これにより、いちいちフルパスを指定しなくても、プロジェクトに応じたPythonが自然に選択されます。

導入する実務的なメリット

現場でpyenvを導入するメリットは、主に次のようなポイントに集約されます。

まず、複数プロジェクトの共存がしやすくなります。

ある案件はPython 3.8、別の案件はクライアント要件で3.9固定、といった状況でも、pyenvを使えば簡単に切り替えられます。

また、既存のシステムPythonを汚さずに済みます。

OSのPythonを直接アップグレードしてしまうと、Ansibleやyum、aptなど、OS側ツールが壊れるリスクがありますが、pyenvはユーザー領域にインストールするため、このリスクを避けられます。

さらに、チームで環境を合わせやすくなります。

.python-versionファイルをリポジトリに含めることで、「このプロジェクトはPython 3.10.6で動かす」といったルールをコード化できます。

新メンバーの環境構築も、バージョン指定が明確になるためスムーズになります。

pyenv-virtualenvとの違いと役割分担

pyenvは「Python本体のバージョン」を管理するツールです。

一方で、プロジェクトごとにインストールするライブラリ群を分離して管理するには、仮想環境(virtualenvやvenv)が必要になります。

pyenvとpyenv-virtualenvの役割

少し整理してみます。

  • pyenv
    Pythonインタプリタ本体のバージョンをインストール・切り替えするツールです。例として、Python 3.9.13本体を導入・削除したり、どのバージョンを使うかをグローバルやローカルで指定したりします。
  • pyenv-virtualenv
    pyenvの拡張プラグインとして動作し、特定バージョンのPythonの上に複数の仮想環境を作るためのツールです。仮想環境ごとにpipで入れるパッケージを分離できるため、プロジェクト間で依存ライブラリの競合を防げます。

役割分担のイメージ

たとえば、Python 3.10.6をpyenvでインストールし、その上に「projectA」「projectB」用の2つの仮想環境をpyenv-virtualenvで作る、という構成が典型例です。

Python本体の更新や切り替えはpyenvに任せ、プロジェクト単位でのパッケージ管理はpyenv-virtualenv(あるいはpython -m venv)に任せる、という役割分担になります。

他のPythonバージョン管理ツールとの比較

pyenv以外にもPythonバージョンを扱えるツールはいくつかあります。

それぞれの特徴を理解しておくと、プロジェクトに応じて適切な選択や組み合わせがしやすくなります。

代表的なツールとの機能比較

以下の表は、よく使われるツールの役割を大まかに整理したものです。

ツール主な役割仮想環境パッケージ管理他言語対応
pyenvPythonバージョン管理プラグイン(pyenv-virtualenv)pipと併用なし
conda/minicondaPythonとパッケージの統合管理あり(環境)conda/pip一部あり
asdf複数言語のバージョン管理プラグインで対応pipなどあり
system PythonOS標準のPythonなしpipなし

現場でよくあるパターンとしては、サーバサイド開発ではpyenv＋(pyenv-virtualenvまたはvenv)、データサイエンス用途ではconda系、といった棲み分けが多いです。

pyenvはOSに優しく、挙動がシンプルで読みやすいという利点があり、LinuxやmacOSでのWebアプリケーション開発・API開発・スクリプト運用などに特に向いています。

現場で使えるpyenvのインストールと初期設定

macOSでのpyenvインストール手順

macOSでは、Homebrewを利用するのが最も簡単です。

ここではzshを使っている前提で説明しますが、bashの場合もほぼ同様です。

1.Homebrewの導入確認

ターミナルで次のコマンドを実行し、Homebrewが入っているか確認します。

Shell
brew --version

バージョンが表示されなければ、公式サイトの指示に従ってHomebrewをインストールします。

2.pyenvのインストール

Homebrewでpyenvをインストールします。

Shell
brew update
brew install pyenv

3.zshへの設定追加

インストールしただけではpyenvは有効になりません。

起動時にpyenvを読み込む設定を、~/.zshrcなどのシェル設定ファイルに追記します。

Shell
# ~/.zshrc の末尾に追記する例

# pyenvの初期化
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

# シェル起動時にpyenvを有効化
eval "$(pyenv init -)"

設定を反映するため、シェルを再起動するか、次のコマンドを実行します。

Shell
source ~/.zshrc

4.インストール確認

最後に、pyenvが有効になっているか確認します。

Shell
pyenv --version
pyenv versions

問題なくバージョン一覧などが表示されれば、macOSでのpyenv導入は完了です。

Linux(Ubuntu)でのpyenvインストール手順

Ubuntuでは、ビルドに必要なパッケージを事前に入れた上で、公式のインストールスクリプトまたはgit cloneで導入する方法が一般的です。

1.ビルドに必要なパッケージをインストール

Pythonをソースからビルドするためのライブラリを先に入れておきます。

Shell
sudo apt update
sudo apt 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

2.pyenv本体をgit clone

ホームディレクトリ配下にpyenvを配置します。

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

3.bash/zshへの設定追加

bashの例を示します。

zshの場合は~/.zshrcに同様の設定を行います。

Shell
# ~/.bashrc の末尾に追記

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"

# pyenvを初期化
eval "$(pyenv init -)"

設定を反映します。

Shell
source ~/.bashrc

4.動作確認

Shell
pyenv --version
pyenv versions

これでUbuntu上でもpyenvが利用可能になります。

Windowsでのpyenv利用(pyenv-win)のポイント

Windowsにはオリジナルのpyenvはそのままでは使えず、pyenv-winという派生プロジェクトを利用します。

概念は同じですが、内部実装やサポート状況が多少異なります。

pyenv-winのインストール例(Chocolatey)

Chocolateyを使っている場合、管理者権限のPowerShellで次のようにインストールできます。

PowerShell
choco install pyenv-win

その後、環境変数PATHなどを設定する必要があります。

一般的にはインストーラーが自動設定しますが、うまくいかない場合は公式ドキュメントを参照しながら%USERPROFILE%.pyenv\pyenv-win\binなどをPATHに追加します。

Windowsでの注意点

Windowsでは、ビルドではなく公式バイナリからPythonを取得するケースが多く、Linux/macOS版pyenvと比べて挙動が異なる部分もあります。

また、企業環境ではセキュリティポリシー上、実行ポリシーやインストール先に制約がある場合も多いため、事前にIT部門のガイドラインを確認しておくことをおすすめします。

シェル設定(zsh・bash)へのpyenvの組み込み

pyenvをインストールしただけでは、ターミナル起動時に自動で有効になりません。

毎回手動でeval "$(pyenv init -)"を打つのは現実的でないため、zshやbashの設定ファイルに組み込んでおきます。

典型的な設定例(zsh)

Shell
# ~/.zshrc

# pyenvのルートパス
export PYENV_ROOT="$HOME/.pyenv"

# pyenvの実行ファイルをPATHに追加
export PATH="$PYENV_ROOT/bin:$PATH"

# シェル起動時にpyenvを有効化
eval "$(pyenv init -)"

これにより、ターミナルを開いた瞬間から「pyenv経由で選ばれたPython」がpythonコマンドとして使われるようになります。

python-buildの導入とビルドに必要なライブラリ

pyenvは内部的にpython-buildというプラグインを使ってPythonをビルド・インストールします。

Homebrewなどでインストールした場合、多くは自動的に含まれていますが、git cloneで導入した場合にはpyenv/plugins配下にインストールされているか確認しておくと安心です。

python-buildの確認例

Shell
ls ~/.pyenv/plugins

ここにpython-buildディレクトリがあれば、通常は問題ありません。

ビルドに必要なライブラリ(再掲)

Ubuntuで紹介したような、SSL、zlib、readline、sqliteなどの開発用ライブラリが不足していると、pyenv installでエラーになる場合があります。

エラーが出た際には、メッセージ内のヒントを読み取り、対応する-devパッケージを追加インストールすることが重要です。

実務で役立つpyenvの基本操作と使い分け

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

pyenvでどのバージョンがインストールできるかを確認するには、次のコマンドを使います。

Shell
pyenv install --list

かなり多くのバージョンが表示されるため、grepで絞り込むと扱いやすくなります。

Shell
# 3.10系だけを表示する例
pyenv install --list | grep " 3\.10"

この一覧から、実務で必要なバージョン(例えば3.8.16や3.10.6など)を選んでインストールします。

pyenv installでPythonをインストールする手順

具体的なインストール手順を見ていきます。

Shell
# 例: Python 3.10.6 をインストール
pyenv install 3.10.6

ビルドには多少時間がかかるため、CPU性能によっては数分待つことになります。

完了後、次のコマンドでインストール済みバージョンを確認します。

Shell
pyenv versions
実行結果
* system (set by /Users/you/.pyenv/version)
  3.10.6

ここでsystemはOS標準のPythonを指し、3.10.6が新たに追加されたバージョンです。

global・local・shellでPythonバージョンを切り替える

pyenvは、以下の3つのレベルでバージョンを指定できます。

  • global: マシン全体のデフォルト
  • local: ディレクトリ(プロジェクト)単位
  • shell: 今開いているシェルセッションだけ

global(全体デフォルト)の設定

Shell
# グローバルで3.10.6を使う
pyenv global 3.10.6

# 現在の有効バージョンを確認
pyenv version
python --version

pyenv globalは~/.pyenv/versionに設定を書き込みます。

local(ディレクトリ単位)の設定

Shell
cd /path/to/your-project

# このディレクトリでは3.9.13を使う
pyenv local 3.9.13

この操作により、カレントディレクトリに.python-versionファイルが作成されます。

このディレクトリ配下では、自動的に3.9.13が有効になります。

shell(セッションのみ)の設定

Shell
# 一時的に3.8.16を使いたい場合
pyenv shell 3.8.16

# 元に戻す
pyenv shell --unset

これはPYENV_VERSION環境変数をセットする操作であり、現在のシェルから抜ければ元に戻ります。

プロジェクトごとにPythonバージョンを固定する

実務では、プロジェクトディレクトリに.python-versionを置き、チーム全員で同じバージョンを使うことが重要です。

プロジェクトでの設定手順

Shell
cd /path/to/project

# 必要なPythonバージョンをインストール
pyenv install 3.9.13

# プロジェクトディレクトリでバージョンを固定
pyenv local 3.9.13

すると、.python-versionは次のような内容になります。

3.9.13

このファイルをGit管理下に置くことで、クローンしてきたメンバーもpyenvさえ入っていれば同じバージョンを自動的に使えるようになります。

システムPythonとの共存と注意点

pyenvはシステムPythonを上書きせず、ユーザー領域に別途Pythonを置きます。

そのため、OSの機能やシステムツールが依存しているPythonを壊さずに済みます。

注意点1: PATHの順序

pyenvが提供するshimsディレクトリがPATHの先頭にあることが重要です。

もし順序が逆になっていると、意図せずシステムPythonが呼ばれてしまう場合があります。

PATHの確認は次のように行えます。

Shell
echo $PATH

注意点2: システム領域へのpipインストール

sudo付きでpip installを実行すると、システムPython側にパッケージが入ってしまうことがあります。

pyenv＋仮想環境を利用する場合、原則としてsudo pip installは使用しない運用にすることを強くおすすめします。

既存プロジェクトにpyenvを導入する手順

既に動いているプロジェクトにpyenvを入れるときは、次のような手順で行うと安全です。

  1. 現在使用しているPythonバージョンを確認する
    例えば、サーバでpython --versionやアプリのログなどから、「本番は3.8.10で動いている」といった情報を収集します。
  2. 同じバージョンをpyenvでインストールする
    pyenv install 3.8.10
  3. プロジェクトディレクトリに移動し、pyenv localで固定する
    cd /path/to/existing-project
pyenv local 3.8.10
  4. 動作確認を行う
    テストやアプリ起動を行い、pyenv経由でも同じように動くかを確認します。
  5. 問題なければ、.python-versionをリポジトリにコミットする

この手順を丁寧に踏むことで、本番環境と同一バージョンをローカルでも再現しつつ、徐々にpyenvへの移行を進められます。

pyenvと仮想環境(virtualenv)による開発環境構築

pyenv-virtualenvで仮想環境を作成・切り替え

pyenv-virtualenvを導入すると、バージョン管理と仮想環境管理を一体的に扱えるようになります。

pyenv-virtualenvのインストール

Homebrew利用の場合:

Shell
brew install pyenv-virtualenv

git cloneでpyenvを入れている場合は、プラグインとして追加します。

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

シェル設定ファイルに次を追記し、起動時に有効化します。

Shell
# ~/.zshrc など

eval "$(pyenv virtualenv-init -)"

仮想環境の作成

Shell
# まずベースとなるPythonを用意
pyenv install 3.10.6

# 3.10.6をベースに "projectA-3.10" という仮想環境を作る
pyenv virtualenv 3.10.6 projectA-3.10

仮想環境の切り替え

Shell
# 仮想環境を有効化
pyenv activate projectA-3.10

# Pythonのバージョン確認
python --version

# 仮想環境を無効化
pyenv deactivate

この操作により、pipでインストールされるパッケージが仮想環境内に隔離されます。

プロジェクトフォルダと仮想環境の紐付け

pyenv-virtualenvはpyenv localと組み合わせることで、ディレクトリに入ったとき自動で仮想環境を切り替えることができます。

紐付け手順

Shell
cd /path/to/projectA

# 仮想環境をprojectAディレクトリに紐付け
pyenv local projectA-3.10

この状態でターミナルを再起動したり、別ディレクトリからcd /path/to/projectAで入ると、自動的にprojectA-3.10環境がアクティブになります。

これにより、「cdするだけでそのプロジェクト用のPythonとパッケージが整う」運用が実現できます。

requirements.txtとpipで依存関係を管理する

仮想環境を使う目的の1つは、依存パッケージをプロジェクト単位で管理し、再現可能な環境を構築することです。

そのためにrequirements.txtを活用します。

現在の仮想環境からrequirements.txtを作成

Shell
# 必ず対象仮想環境を有効化してから実行
pyenv activate projectA-3.10

pip freeze > requirements.txt

requirements.txtから環境を再現

Shell
pyenv activate projectA-3.10

pip install -r requirements.txt

新しいメンバーがプロジェクトに参加したときも、pyenvでバージョンと仮想環境を合わせ、pip install -r requirements.txtするだけで同じ環境を構築できます。

VSCodeなどIDEでpyenv環境を認識させる設定

VSCodeなどのIDEを利用する場合は、pyenvやpyenv-virtualenvで作成したPythonをインタプリタとして選択する必要があります。

VSCodeでの設定手順(概要)

  1. VSCodeの左下に表示されているPythonバージョン部分をクリックします。
  2. 「Pythonインタープリターの選択」画面が開くので、一覧の中からpyenvの仮想環境パスを選びます。
    例:~/.pyenv/versions/projectA-3.10/bin/python のようなパスです。
  3. プロジェクトごとに.vscode/settings.jsonが作成され、その中に選択したPythonパスが記録されます。

これにより、VSCodeのターミナル、デバッグ実行、Lint、フォーマッタなどが、プロジェクトに対応したpyenv環境のPythonを使うようになります。

チーム開発でのpyenv活用

チーム開発では、「誰のマシンでも同じように動くか」を担保することがとても重要です。

pyenvと仮想環境を組み合わせることで、次のような運用が可能になります。

チームでのおすすめ運用パターン

  1. プロジェクトのトップディレクトリに、使用するPythonバージョンを記した.python-versionを置く。
  2. 各自がpyenvで同じバージョンをインストールし、pyenv localで紐付ける。
  3. 仮想環境名もある程度のルール(例: {project-name}-{python-version})で揃える。
  4. 依存パッケージはrequirements.txtやpoetry.lockなどで管理し、更新時にはチーム内で共有する。
  5. 「環境構築手順書」あるいはsetup.shのようなスクリプトに、pyenvと仮想環境の準備手順も含めておく。

これらを整備しておくと、新メンバーが参加した際にも、短時間で同一のPython実行環境を再現でき、環境差異によるバグや「自分の環境では動く」問題を大幅に減らせます。

まとめ

pyenvは、Pythonのバージョンを安全かつ柔軟に切り替えるための強力なツールです。

macOSやLinuxでは、OS標準のPythonを汚さずに複数バージョンを共存させ、global・local・shellの3段階で適切に制御できます。

さらにpyenv-virtualenvと組み合わせれば、プロジェクトごとの仮想環境と依存関係をきちんと分離でき、個人開発からチーム開発まで一貫した環境管理が可能になります。

本記事を参考に、自身の現場に合った運用ルールとテンプレートを整備し、再現性の高いPython開発環境を構築してみてください。

環境構築・パッケージ管理

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

URLをコピーしました！