はじめに (対象読者・この記事でわかること)

本記事は、macOS・Linux で pyenv を使い始めたものの、インストールした Python バージョンやシステムのデフォルトが乱れてしまい、以前と同じ環境でスクリプトを走らせられなくなった開発者・エンジニアを対象としています。
この記事を読むことで、以下ができるようになります。

  • pyenv によって変更されたシステム Python の状態を正確に把握する方法
  • 望ましいバージョンを再度 global または local に設定し、元の環境へ安全に復元する手順
  • 復元作業中に遭遇しやすいエラーの原因と対処法

pyenv の導入が増える一方で、環境の「巻き戻し」情報は散在しており、本記事は実務ですぐに役立つ実践的ガイドとして執筆しました。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • 基本的なシェル操作（bash/zsh）と環境変数の概念
  • Python のバージョン管理や仮想環境（venv、virtualenv）の基礎知識
  • macOS の場合は Homebrew、Linux の場合は apt/yum 等のパッケージマネージャの基本操作

pyenv で変わった環境の概要と背景

pyenv は「任意の Python バージョンを簡単に切り替えられる」便利なツールですが、pyenv global や pyenv local を誤って設定すると、システムが参照する python3 コマンドが期待したバージョンと食い違うことがあります。特に以下のケースで悩むことが多いです。

  1. 複数バージョンのインストール後に global が上書きされた
    例: pyenv install 3.9.13 → pyenv global 3.9.13 → その後 pyenv install 3.11.5 → pyenv global 3.11.5。結果、元々動かしていたスクリプトが 3.9 系でしか動かないのに 3.11 系が呼ばれる。

  2. プロジェクトディレクトリで pyenv local が残存
    .python-version ファイルが残っていると、ターミナルを開くだけでローカルバージョンが適用され、システム全体の挙動が変わります。

  3. シェルの初期化スクリプトが二重に設定
    .bashrc と .zshrc の両方に eval "$(pyenv init -)" が書かれていると、shims のパスが重複し、期待しない Python が解決されることがあります。

このような状態になると、which python が ~/.pyenv/shims/python を指し、python --version が意図しないバージョンを出力します。そこで、「元のシステム Python（例: macOS の /usr/bin/python3、Ubuntu の /usr/bin/python3.8）」に戻すことが求められます。次の章では、具体的な復元手順をステップごとに解説します。

元の Python 環境へ復元する具体的な手順

ステップ1　現在の pyenv 状態を確認する

まずは、現在の pyenv 設定とインストール済みバージョンを一覧化します。

Bash

# pyenv が有効か確認
pyenv version

# グローバル設定とローカル設定を表示
pyenv global
pyenv local  # カレントディレクトリで有効なローカル設定

# インストール済みバージョン一覧
pyenv versions

上記コマンドで得られる出力例:

system (set by /home/user/.pyenv/version)
  3.9.13
* 3.11.5 (set by /home/user/.pyenv/version)

system が システムに付属している Python を示しています。* が現在有効なバージョンです。ここで、system が表示されていない、あるいは local の .python-version が残っている 場合は、次のステップで対処します。

ステップ2　不要なローカル設定とシェルの初期化をクリーンアップ

2-1　ローカル設定ファイルの削除

プロジェクトディレクトリ直下に .python-version が存在すれば、以下コマンドで削除します。

Bash

# カレントディレクトリの .python-version を確認
ls -a | grep .python-version

# 削除（必要に応じてバックアップを取る）
rm .python-version

2-2　シェル初期化スクリプトの整理

.bashrc、.zshrc、.profile などに重複して書かれた pyenv 初期化行を一つにまとめます。

Bash

# 例: .zshrc の該当箇所
# 既存
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

# 重複があれば削除し、1 行に統一
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"

変更後はシェルを再起動または source ~/.zshrc で反映させます。

ステップ3　global 設定を system に戻す

pyenv の global 設定を system に変更します。

Bash

pyenv global system

この操作で、pyenv which python が ~/.pyenv/shims/python ではなく、システムの実体パス（例: /usr/bin/python3）を指すようになります。確認は以下です。

Bash

python3 --version          # 期待したシステムバージョンが出るか
which python3              # /usr/bin/python3 が表示されるか

ステップ4　shims の再生成とキャッシュクリア

pyenv rehash で shims を最新状態にし、キャッシュが残っている場合は削除します。

Bash

pyenv rehash
# pyenv のキャッシュクリア
rm -rf "$(pyenv root)/cache"

ステップ5　システム Python のアップデート（必要なら）

システム側の Python が古すぎる場合は、パッケージマネージャで更新します（macOS は Homebrew、Ubuntu は apt など）。

macOS（Homebrew）

Bash

brew install python@3.11   # 例: 3.11 系をインストール
brew unlink python@3.9
brew link --overwrite python@3.11

Ubuntu（apt）

Bash

sudo apt update
sudo apt install python3.10
# デフォルトの python3 を 3.10 に切り替える
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 110

インストール後、再度 python3 --version で期待通りのバージョンが出たことを確認します。

ハマった点やエラー解決

発生したエラー 原因 解決策
pyenv: command not found pyenv の PATH がシェルに登録されていない .bashrc / .zshrc に export PATH="$HOME/.pyenv/bin:$PATH" を追記し、シェルを再読込
python3: no such file or directory (global 設定後) pyenv global system 後にシステム Python が削除されていた OS のパッケージマネージャでシステム Python を再インストール
pyenv rehash が失敗 ~/.pyenv/shims ディレクトリの権限が不正 chmod -R u+rw ~/.pyenv で権限を修正
.python-version が残り続ける プロジェクトディレクトリがサブモジュールで、内部に別の .python-version がある find . -name ".python-version" で全箇所を検索し、不要なファイルを削除

解決策のまとめ

  1. 状態確認 → pyenv version・pyenv versions で現在の設定を把握
  2. ローカルファイル除去 → .python-version を削除し、シェル初期化行を整理
  3. global を system に設定 → pyenv global system でシステム Python に戻す
  4. shims 再生成 & キャッシュクリア → pyenv rehash とキャッシュ削除
  5. システム Python のバージョン調整 → 必要に応じてパッケージマネージャでインストール・切替

上記手順を順に実行すれば、pyenv によって乱れた環境は確実に元通りになり、開発作業に支障をきたすことはなくなります。

まとめ

本記事では、pyenv の設定ミスやローカルバージョンの残存により変わってしまった Python 環境を、システムの標準 Python に安全に戻す手順 を解説しました。

  • 状態確認と不要設定の除去で根本原因を特定
  • global を system に変更し、システム Python を再び参照させる
  • shims 再生成・キャッシュクリアで残存情報を一掃
  • OS パッケージマネージャでのバージョン管理で長期的な安定性を確保

これらを実践することで、開発者は環境トラブルに振り回されず、コードの品質向上と作業効率の向上を実感できるでしょう。次回は、pyenv と virtualenv/venv を併用したベストプラクティスについて解説する予定です。

参考資料