Linuxで複数バージョンのPythonを安全に切り替える pyenv + virtualenv 実戦ガイド

LINUX

2025.09.02

Pythonは開発現場で欠かせない言語ですが、プロジェクトごとに異なるPythonバージョンを要求されることは珍しくありません。
「あるアプリはPython 3.7が必要、でも別の案件では3.11を使いたい…」といった状況で、システムのPythonに直接手を入れてしまうと依存関係の崩壊やライブラリの衝突を招きます。

そこで登場するのが pyenv と pyenv-virtualenv。
これらを組み合わせることで、複数のPythonバージョンを安全に切り替えつつ、プロジェクト単位で仮想環境を作成・管理できます。

1. なぜ pyenv + virtualenv が必要なのか？
1. 開発現場でのよくある悩み
2. pyenvのインストール
3. Pythonバージョンのインストールと切り替え
4. pyenv-virtualenv の導入
5. プロジェクト単位で環境を固定する
6. よくあるトラブルと解決法
7. まとめ

1. なぜ pyenv + virtualenv が必要なのか？

開発現場でのよくある悩み

OS標準のPythonにpip installして依存が壊れる
プロジェクトごとにライブラリのバージョンが異なり混乱
「pip freeze > requirements.txt」で再現しようとしても動かない
システム全体に影響を与えない形でPythonを切り替えたい

これらの悩みを解決するのが pyenv（バージョン切り替え） と virtualenv（環境分離） です。

2. pyenvのインストール

まず、必要なパッケージをインストールします。

sudo apt update
sudo apt install -y \
    git 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 python3-openssl

次に、pyenvをクローンしてPATHを通します。

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

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc

source ~/.bashrc

インストール確認

pyenv --version

3. Pythonバージョンのインストールと切り替え

利用可能なバージョン一覧を確認

pyenv install --list

例えば Python 3.7.17 と 3.11.6 をインストールする場合

pyenv install 3.7.17
pyenv install 3.11.6

切り替え例

# グローバル（システム全体）
pyenv global 3.11.6

# カレントディレクトリ限定（プロジェクトごと）
pyenv local 3.7.17

# シェル限定
pyenv shell 3.11.6

現在のバージョン確認

python --version

4. pyenv-virtualenv の導入

仮想環境管理を簡単にするために pyenv-virtualenv を追加します。

git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenv

echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
source ~/.bashrc

仮想環境の作成

pyenv virtualenv 3.11.6 myproject-env

環境の切り替え

pyenv activate myproject-env
(pyenv) python --version
pyenv deactivate

5. プロジェクト単位で環境を固定する

プロジェクトディレクトリで以下を実行

cd ~/work/myproject
pyenv local myproject-env

この設定をすると、そのディレクトリに入るだけで自動的に仮想環境が有効になります。
チーム開発では .python-version をGit管理に含めることで、誰が開発しても同じ環境を再現できます。

6. よくあるトラブルと解決法

ビルドに失敗する
→ libssl-dev や zlib1g-dev が不足していないか確認。
pipが古い
→ pip install --upgrade pip で更新。
仮想環境が有効にならない
→ .bashrc に eval "$(pyenv init --path)" と eval "$(pyenv virtualenv-init -)" が入っているか確認。