pyenvとは｜インストール・使い方・仕組みとエラーの直し方

python と打つと、まず pyenv の shim が呼ばれ、pyenv が決めた版の本物の Python に引き渡されます。

flowchart TD
    U[python と入力] --> S[shims の python<br>PATH の先頭]
    S --> P[pyenv が版を決める]
    P --> V[.python-version など<br>設定を読む]
    V --> R[versions/3.14.8/bin/python<br>を実行]

よく使う操作を先にまとめます。

やりたいこと	コマンド	補足
Python を入れる	pyenv install 3.15.0	ソースからビルドする
いつも使う版を決める	pyenv global 3.15.0	~/.pyenv/version に書く
このフォルダだけ版を変える	pyenv local 3.14.8	.python-version を作る
今の端末だけ版を変える	pyenv shell 3.14.8	端末を閉じると戻る
今の版と、決まった理由を見る	pyenv version	どのファイルで決まったかが出る
入っている版の一覧	pyenv versions	* が今使われている版
入れられる版の一覧	pyenv install --list	1,128件あった
版を消す	pyenv uninstall 3.15.0	確認が出る

確認環境：Ubuntu 24.04・pyenv 2.8.10（公式インストーラーで導入）・GCC 13.3.0・uv 0.13.1。Python 3.15.0 と 3.14.8 を pyenv でビルドし、切り替え・shims・venv・uv との組み合わせ・ビルドの失敗と直し方を、bash で実際に動かした出力を載せています。Python のソースは pyenv のキャッシュ（~/.pyenv/cache）に置き、pyenv の定義ファイルの SHA-256 と一致するものを使いました。Mac の Homebrew 手順・Windows の pyenv-win は、pyenv の README・Wiki、Homebrew の formula ページ、pyenv-win の README で確かめました（確認日 2026年10月17日）。

pyenvとは

pyenv（パイエンブ）は、Python の版（バージョン）を切り替えるためのツールです。 「3.15 で新しいアプリを作りつつ、保守しているアプリは 3.14 のまま動かす」といった使い分けを、1台の PC でできるようにします。Ruby の rbenv をもとに作られ、シェルスクリプトだけで書かれています。

公式の README は、pyenv ができることを次のように挙げています。

• ユーザーごとに、ふだん使う Python の版を変える
• プロジェクト（フォルダ）ごとに、Python の版を決める
• 環境変数で、その場だけ版を上書きする
• CPython のほか、PyPy・GraalPy・Miniconda なども入れられる

反対に、pyenv 自身はパッケージ（ライブラリ）の管理や仮想環境の管理はしません。 README にも「virtualenv は管理しない（Manage virtualenv）」と書かれています。ライブラリを分けたいときは、venv や pyenv-virtualenv プラグインと組み合わせます（後の「venv・uvとの違い」で比べます）。

pyenvが必要になる場面

場面	pyenv で解決すること
案件ごとに Python の版が違う	フォルダに入るだけで版が切り替わる
OS の Python を触りたくない	ホームの下に別の Python を入れる。OS 側は変えない
新しい版（3.15 など）を試したい	今の版を残したまま、横に入れて試せる
複数の版でテストしたい	pyenv global 3.15.0 3.14.8 で両方を同時に使える

pyenvのインストール（Mac・Linux・Windows）

OS ごとに入れ方が違います。Windows では pyenv 本体は動きません（README：「Pyenv does not officially support Windows」）。Windows では別のプロジェクトの pyenv-win を使います。

OS	入れ方	2026年10月17日時点の版
Mac	Homebrew：brew install pyenv	2.8.10（Homebrew の formula）
Linux	公式インストーラー：curl -fsSL https://pyenv.run | bash	2.8.10（GitHub の最新）
Windows	pyenv-win（PowerShell のスクリプト）	3.1.1（pyenv-win のリポジトリ）
WSL	Linux と同じ	2.8.10

Macでのインストール（Homebrew）

Homebrew の formula の版は 2026年10月17日時点で 2.8.10 です。依存として openssl@4・readline・autoconf・pkgconf も入ります。

brew update
brew install pyenv

続けて、シェルの設定ファイルに pyenv の設定を足します（Mac の標準のシェルは zsh です）。pyenv init --install は、使っているシェルの設定ファイルに推奨の3行を書き足すコマンドです。

pyenv init --install
exec "$SHELL"

手で書く場合は、~/.zshrc の末尾に次の3行を足します（README の Zsh の手順と同じ内容です）。

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"

Python をビルドするために、Xcode Command Line Tools と、Wiki の「Suggested build environment」にあるライブラリを入れておきます。

xcode-select --install
brew install openssl@3 openssl readline sqlite3 xz tcl-tk@8 libb2 zstd zlib pkgconfig

Linuxでのインストール（公式インストーラー）

Linux では、README が「Recommended」としている自動インストーラーを使います。中身は、pyenv 本体と3つのプラグイン（pyenv-doctor・pyenv-update・pyenv-virtualenv）を git clone するスクリプトです。

インストーラーを実行したときの出力です。最後に「まだ PATH に入っていない」という警告と、足すべき設定が表示されます。

curl -fsSL https://pyenv.run | bash

Cloning into '/home/user/.pyenv'...
Cloning into '/home/user/.pyenv/plugins/pyenv-doctor'...
Cloning into '/home/user/.pyenv/plugins/pyenv-update'...
Cloning into '/home/user/.pyenv/plugins/pyenv-virtualenv'...

WARNING: seems you still have not added 'pyenv' to the load path.

# Load pyenv automatically by appending
# the following to 
# ~/.bash_profile if it exists, otherwise ~/.profile (for login shells)
# and ~/.bashrc (for interactive shells) :

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"

# Restart your shell for the changes to take effect.

# Load pyenv-virtualenv automatically by adding
# the following to ~/.bashrc:

eval "$(pyenv virtualenv-init -)"

この時点では、まだ pyenv コマンドは使えません。

$ pyenv --version
bash: pyenv: command not found

pyenv init --install を実行すると、何も表示せずに設定ファイルへ書き足します。書き足された ~/.bashrc の中身です（~/.profile にも同じ3行が入りました）。

~/.pyenv/bin/pyenv init --install

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - bash)"

もう一度実行したときは、書き足さずに次のメッセージで止まりました。

pyenv: cannot automatically apply changes to /home/user/.bashrc: it appears to already contain Pyenv-related code.
pyenv: review the file's contents and apply changes manually if necessary.
pyenv: run `pyenv init bash` to see the suggested setup.

シェルを開き直すと、PATH の先頭に shims と pyenv 本体のフォルダが入ります。

$ exec "$SHELL"
$ pyenv --version
pyenv 2.8.10
$ echo $PATH
/home/user/.pyenv/shims:/home/user/.pyenv/bin:/usr/local/bin:/usr/bin:/bin
$ pyenv versions
* system (set by /home/user/.pyenv/version)

README によると、Debian 系の標準の ~/.profile は ~/.bashrc を読んだあとに PATH を書き換えるため、~/.bashrc と ~/.profile の両方に書くのが確実です。BASH_ENV が .bashrc を指している環境では、.bashrc ではなく .bash_profile だけに書くよう注意書きがあります。

関連記事「Linux環境変数PATHの設定方法｜exportと.bashrcの使い分け早見表」で扱っています。

ビルドに必要なパッケージ（OS別）

pyenv install は、Python をソースからビルド（コンパイル）して入れます。 そのため、C コンパイラと各種ライブラリの開発用パッケージが要ります。Wiki の「Suggested build environment」のコマンドです。

OS	コマンド
Ubuntu・Debian・Mint	sudo apt update; sudo apt install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev curl git libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libzstd-dev
Fedora 22 以上	dnf install make gcc patch zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel libuuid-devel gdbm-libs libnsl2
CentOS・Amazon Linux 2	yum install gcc make patch zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel（Amazon Linux 2 は openssl11-devel）
Mac	xcode-select --install と brew install openssl@3 openssl readline sqlite3 xz tcl-tk@8 libb2 zstd zlib pkgconfig

Ubuntu・Debian では、pyenv 2.8.6 で入った pyenv install-prerequisites でも入れられます。中身は上とほぼ同じ一覧を sudo apt-get install するスクリプトで、-a を付けると任意の libgdbm-dev も入ります。

$ pyenv help install-prerequisites
Usage: pyenv install-prerequisites [-a|--all]

  -a/--all       Also install optional dependencies (for rarely used modules)

pyenv doctor（インストーラーで入るプラグイン）は、ビルドに要るものがそろっているかを確かめます。

$ pyenv doctor
Cloning /home/user/.pyenv/plugins/pyenv-doctor/bin/.....
Installing python-pyenv-doctor...
Installed python-pyenv-doctor to /home/user/tmp/pyenv-doctor.20261017120734.10706/prefix
Congratulations! You are ready to build pythons!

ただし、このとき tk-dev と libzstd-dev が入っていなくても「ready」と出ました。doctor が通っても、tkinter などが欠けた Python になることがあります（後の「よくあるエラー」で実例を載せます）。

Windowsでのインストール（pyenv-win）

Windows では pyenv-win を使います。README の Quick start のコマンドを PowerShell で実行します。

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"

そのあと PowerShell を開き直し、pyenv --version で版が出るかを確かめます。pyenv-win のドキュメントにある、つまずきやすい点は次のとおりです。

症状	原因	直し方（pyenv-win のドキュメントより）
cannot be loaded because running scripts is disabled on this system（UnauthorizedAccess）	PowerShell の実行ポリシー	管理者の PowerShell で Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine を実行し、やり直す
pyenv が command not found	PATH に .pyenv\pyenv-win\bin と \shims が無い・優先度が低い	環境変数 PATH の上位に2つを入れる。VS Code など IDE は再起動する
python で Microsoft Store が開く	Windows のアプリ実行エイリアス	「アプリ実行エイリアスの管理」で Python の「App Installer」をオフにする
pip で入れたコマンドが動かない	shims が更新されていない	pyenv rehash を実行する（.pyenv フォルダの外で）

pyenv-win のコマンドは pyenv とほぼ同じ名前です（install・global・local・shell・versions・version・which・whence・exec・rehash・uninstall・update など）。違いは、Python をソースからビルドせず、Windows 用のインストーラーで入れる点です。README には「インストールのウィザードが出ることがある」と書かれています。pyenv init のシェル設定は無く、PATH は環境変数に直接入れます。

pyenvの使い方：Pythonをインストールする

入れられる版を調べる

pyenv install --list は、pyenv が入れ方を知っている版（定義ファイル）の一覧です。pyenv 2.8.10 では 1,128 件あり、CPython のほか PyPy・Miniconda なども含みます。

$ pyenv install --list | grep -c .
1128
$ pyenv install --list | grep -E "^ +3\.1[3-6]" | tail -8
  3.15.0
  3.15.0t
  3.15-dev
  3.15t-dev
  3.16.0a1
  3.16.0a1t
  3.16-dev
  3.16t-dev

末尾の t はフリースレッド版（GIL なしでビルドした版）、-dev は開発中のブランチ、a1 はアルファ版です。「3」や「3.14」のように途中まで書くと、その系列の最新を指します。 pyenv latest -k で、install がどの版を選ぶかを確かめられます。

$ pyenv latest -k 3
3.15.0
$ pyenv latest -k 3.14
3.14.8

pyenv installでビルドする

pyenv install 3.15.0

成功したときの出力は短く、次の2行だけです（ソースを ~/.pyenv/cache に置いてあったため、ダウンロードの行は出ていません）。ネットから取る場合は、この前に Downloading Python-3.15.0.tar.xz... と取得先の URL が出ます。

Installing Python-3.15.0...
Installed Python-3.15.0 to /home/user/.pyenv/versions/3.15.0

real    3m35.964s
user    4m53.765s
sys 0m29.020s

入った版は pyenv versions で見られます。入れただけでは、まだ切り替わりません（* は system のまま）。

$ pyenv versions
* system (set by /home/user/.pyenv/version)
  3.14.8
  3.15.0

pyenv install の主なオプションです（pyenv help install より）。

オプション	意味
-l / --list	入れられる版の一覧
-f / --force	入っていても入れ直す（依存を足した後の再ビルドに使う）
-s / --skip-existing	入っていれば何もしない
-v / --verbose	コンパイルの経過を表示する
-k / --keep	ビルドしたソースを残す
3.12.0:my-3.12	別名を付けて入れる（同じ版を設定違いで複数持てる。2.8.0 以降）

バージョンを切り替える（global・local・shell）

切り替えのコマンドは3つあり、効く範囲が違います。 同時に設定されていると、範囲の狭いほうが勝ちます。

コマンド	効く範囲	書き込む先
pyenv shell 3.14.8	今開いている端末だけ	環境変数 PYENV_VERSION
pyenv local 3.14.8	そのフォルダと下のフォルダ	そのフォルダの .python-version
pyenv global 3.15.0	そのユーザーの全体	~/.pyenv/version
pyenv global system	OS の Python に戻す	~/.pyenv/version

pyenv global：ふだん使う版を決める

$ pyenv global 3.15.0
$ pyenv version
3.15.0 (set by /home/user/.pyenv/version)
$ python --version
Python 3.15.0
$ which python
/home/user/.pyenv/shims/python
$ pyenv which python
/home/user/.pyenv/versions/3.15.0/bin/python
$ cat ~/.pyenv/version
3.15.0

which python が指すのは shims の中の python です。本物の場所は pyenv which python で分かります。

pyenv local：フォルダごとに版を決める（.python-version）

$ mkdir -p ~/work/legacy-app/src && cd ~/work/legacy-app
$ pyenv local 3.14.8
$ cat .python-version
3.14.8
$ pyenv version
3.14.8 (set by /home/user/work/legacy-app/.python-version)
$ python --version
Python 3.14.8
$ cd src; python --version
Python 3.14.8
$ pyenv version-file
/home/user/work/legacy-app/.python-version
$ cd ~; python --version
Python 3.15.0

.python-version は1行に版の名前を書いただけのテキストファイルです。下のフォルダ（src）でも、親をさかのぼって見つけたファイルが使われます。 ホームに戻ると global の 3.15.0 に戻りました。.python-version は Git にコミットすると、チームで同じ版をそろえやすくなります。

pyenv local 3.14 のように途中まで書くこともできます。ファイルには「3.14」と書かれ、入っている中で最新の 3.14 系が使われます。

$ pyenv local 3.14
$ cat .python-version
3.14
$ python --version
Python 3.14.8

pyenv shell：今の端末だけ版を変える

$ cd ~/work/legacy-app
$ pyenv shell 3.15.0
$ python --version
Python 3.15.0
$ pyenv shell --unset
$ python --version
Python 3.14.8

pyenv shell は PYENV_VERSION という環境変数を設定するだけです。.python-version より優先されるので、local で 3.14.8 にしたフォルダでも 3.15.0 になりました。--unset で消すと、.python-version の 3.14.8 に戻ります。

pyenv shell を使うには、eval "$(pyenv init - bash)" で pyenv がシェルの関数として読み込まれている必要があります。読み込んでいないシェルでは、PYENV_VERSION=3.15.0 python ... のように環境変数を直接付けても同じことができます。

$ PYENV_VERSION=system python --version
Python 3.11.15

複数の版を同時に使う

global・local には複数の版を並べられます。最初の版が python になり、2番目以降は python3.14 のような版付きの名前で呼べます。tox などで複数の版のテストを回すときに使います。

$ pyenv global 3.15.0 3.14.8
$ pyenv versions
  system
* 3.14.8 (set by /home/user/.pyenv/version)
* 3.15.0 (set by /home/user/.pyenv/version)
$ python --version
Python 3.15.0
$ python3.14 --version
Python 3.14.8

pyenvの仕組み（shims）

shimsはpythonコマンドの「入口」

pyenv は ~/.pyenv/shims というフォルダを PATH の先頭に置き、そこに python・pip などと同じ名前の小さなスクリプト（shim）を並べます。 2つの版を入れた後、shims は22個ありました。

$ ls ~/.pyenv/shims | head -12
idle
idle3
idle3.14
idle3.15
pip
pip3
pip3.14
pip3.15
pydoc
pydoc3
pydoc3.14
pydoc3.15

shim の中身です。自分の名前（python）を取り出し、pyenv exec に渡しているだけです。

#!/usr/bin/env bash
set -e
[ -n "$PYENV_DEBUG" ] && set -x

program="${0##*/}"

export PYENV_ROOT="/home/user/.pyenv"
SHIM_PATH=${0%/*}
if [[ $SHIM_PATH != "/home/user/.pyenv/shims" ]]; then
  export _PYENV_SHIM_PATH="$SHIM_PATH"
fi
exec "/home/user/.pyenv/libexec/pyenv" exec "$program" "$@"

版が決まる順番

pyenv exec は、次の順に設定を探し、最初に見つかったものを使います（README の「Understanding Python version selection」）。

flowchart TD
    A[1 環境変数 PYENV_VERSION<br>pyenv shell] -->|無ければ| B[2 今のフォルダの<br>.python-version]
    B -->|無ければ| C[3 親フォルダをさかのぼって<br>.python-version]
    C -->|無ければ| D[4 ~/.pyenv/version<br>pyenv global]
    D -->|無ければ| E[system<br>OS の Python]

決まった理由は pyenv version の「set by」に出ます。版を間違えたと思ったら、まずここを見ます。

system と「すり抜け」

system は「shims より後ろの PATH で見つかる Python」を指します。README によると、選んだ版にそのコマンドが無いときも、shim は PATH の後ろにある同名のコマンドへ「すり抜け」（fall-through）ます。

このすり抜けのために、.python-version に入っていない版が書かれていると、python はエラーにならずに OS の Python で動きました。 エラーが出るのは pyenv version を実行したときだけです。

$ cd ~/work/old        # .python-version に「3.12.11」（入っていない版）
$ python --version
Python 3.11.15
$ pyenv which python
/usr/bin/python
$ pyenv version
pyenv: version `3.12.11' is not installed (set by /home/user/work/old/.python-version)

pyenv global で指定していた版を pyenv uninstall で消したときも同じで、python は黙って OS の Python（/usr/bin/python）になりました。

pip installとrehash

pip でコマンド付きのパッケージを入れると、そのコマンドの shim が作られます（rehash）。pyenv は pip install の後に rehash を自動で行うため、手で pyenv rehash を打たなくても shim ができていました。

$ pip install -q cowsay        # 3.14.8 を使っているフォルダで
$ ls ~/.pyenv/shims | grep cow
cowsay
$ pyenv which cowsay
/home/user/.pyenv/versions/3.14.8/bin/cowsay
$ pyenv whence cowsay
3.14.8

パッケージは版ごとに別々です。 global が 3.15.0 のホームで cowsay を打つと、次のエラーになります。どの版に入っているかが表示されます。

$ cd ~
$ cowsay -t hi
pyenv: cowsay: command not found

The `cowsay' command exists in these Python versions:
  3.14.8

Note: See 'pyenv help global' for tips on allowing multiple
      Python versions to be found at the same time.

関連記事「pipコマンド一覧｜installのバージョン指定とrequirements.txt」で扱っています。

shimsを通すと起動が少し遅くなる

shim は bash のスクリプトなので、python を起動するたびに pyenv の処理が挟まります。python -c pass を50回ずつ実行し、1回あたりの時間を3回測りました。

呼び方	1回あたり（3回の測定）
shim 経由（python）	99・99・97 ミリ秒
本物を直接（~/.pyenv/versions/3.14.8/bin/python）	15・15・17 ミリ秒

1回あたり約80ミリ秒の差です。対話で使うぶんには気になりにくい差ですが、シェルスクリプトで python を何百回も呼ぶときは、pyenv which python で得た本物のパスや、venv の中の python を直接使うと速くなります。

pyenvのコマンド一覧

pyenv 2.8.10 を公式インストーラーで入れたときに pyenv と打つと表示される一覧から、よく使うものをまとめます（activate・virtualenv などはプラグインのコマンドです）。

コマンド	何をするか
pyenv install <版>	Python をビルドして入れる
pyenv uninstall <版>	入れた版を消す
pyenv versions	入っている版の一覧（--bare で名前だけ）
pyenv version	今の版と、決まった理由
pyenv global / local / shell	版を切り替える（範囲：全体／フォルダ／端末）
pyenv which <コマンド>	実際に動く本物のパス
pyenv whence <コマンド>	そのコマンドを持っている版の一覧
pyenv exec <コマンド>	今の版で実行する（shims を使わないとき）
pyenv rehash	shims を作り直す
pyenv latest <途中までの版>	その系列の最新（-k で install 側の候補）
pyenv root / prefix	pyenv のフォルダ・版のフォルダ
pyenv init	シェルの設定（--install で書き込み、--path で PATH だけ）
pyenv install-prerequisites	ビルドに要るパッケージを apt で入れる（Debian 系）
pyenv update	pyenv とプラグインを更新（pyenv-update プラグイン）
pyenv doctor	ビルドの準備ができているか確かめる（pyenv-doctor プラグイン）
pyenv virtualenv <版> <名前>	仮想環境を作る（pyenv-virtualenv プラグイン）
pyenv binary	入れた版を持ち運べる形にまとめる（実験的）

pyenvとvenv・uvの違い

pyenv は「Python 本体の版」を、venv は「プロジェクトごとのライブラリ」を分けます。 役割が違うので、組み合わせて使えます。uv は、Python 本体の取得・仮想環境・パッケージ管理を1つのツールで行います。

観点	pyenv	venv	uv
分けるもの	Python 本体の版	ライブラリ（site-packages）	版・仮想環境・ライブラリ
Python 本体を入れるか	入れる（ソースからビルド）	入れない（今の Python を使う）	入れる（ビルド済みを取得）
版の指定	.python-version	作るときの python で決まる	.python-version・pyproject.toml
実体	シェルスクリプト	Python 標準ライブラリ	1つの実行ファイル
Windows	pyenv-win を使う	そのまま使える	そのまま使える

uv のドキュメントでは、uv が自分で入れる Python は python-build-standalone のビルド済みのもので、見つからないときは自動でダウンロードします。また、uv は pyenv が入れた Python も「システムの Python」として見つけます。

pyenvとvenvを組み合わせる

pyenv で版を決めたフォルダで python -m venv を実行すると、その版の仮想環境ができます。

$ cd ~/work/legacy-app        # .python-version は 3.14.8
$ python -m venv .venv
$ source .venv/bin/activate
$ python --version
Python 3.14.8
$ which python
/home/user/work/legacy-app/.venv/bin/python
$ readlink -f .venv/bin/python
/home/user/.pyenv/versions/3.14.8/bin/python3.14
$ deactivate
$ cat .venv/pyvenv.cfg
home = /home/user/.pyenv/versions/3.14.8/bin
include-system-site-packages = false
version = 3.14.8
executable = /home/user/.pyenv/versions/3.14.8/bin/python3.14
command = /home/user/.pyenv/versions/3.14.8/bin/python -m venv /home/user/work/legacy-app/.venv

venv の中の python は、pyenv の 3.14.8 の本物を指しています。そのため、pyenv uninstall 3.14.8 をすると、この venv も動かなくなります。 版を消す前に、その版で作った venv を確かめます。

関連記事「Python venvの使い方｜仮想環境の作成・有効化・削除をOS別にコピペ」で扱っています。

pyenv-virtualenvで作る

インストーラーで入る pyenv-virtualenv を使うと、仮想環境を pyenv の「版」の1つとして扱えます。pyenv local tools-3.15 のように、フォルダに結び付けられます。

$ pyenv virtualenv 3.15.0 tools-3.15
$ pyenv versions
  system
* 3.14.8 (set by /home/user/work/legacy-app/.python-version)
  3.15.0
  3.15.0/envs/tools-3.15
  tools-3.15 --> /home/user/.pyenv/versions/3.15.0/envs/tools-3.15

uvと組み合わせる

uv 0.13.1 は、pyenv の .python-version をそのまま読みました。UV_PYTHON_DOWNLOADS=never（ダウンロードしない設定）で実行しています。

$ cd ~/work/legacy-app        # .python-version は 3.14.8
$ uv python find
/home/user/.pyenv/versions/3.14.8/bin/python3.14
$ uv venv
Using CPython 3.14.8 interpreter at: /home/user/.pyenv/versions/3.14.8/bin/python3.14
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
$ uv python pin 3.15
Updated `.python-version` from `3.14.8` -> `3.15`
$ python --version
Python 3.15.0

uv python pin が書き換えた .python-version を、pyenv もそのまま読んで 3.15.0 に切り替わりました。.python-version は pyenv と uv で共通の形式です。

関連記事「uvの使い方｜pip・venvからの移行とチーム開発での使い方」で扱っています。

どれを使うか（判断表）

状況	選ぶもの	理由
複数の Python の版を切り替えたい（Mac・Linux）	pyenv	版ごとにビルドして並べられる
同じ版でプロジェクトごとにライブラリを分けたい	venv	標準ライブラリだけで作れる
版もライブラリも1つのツールで管理したい	uv	取得・仮想環境・依存の固定まで行う
自分でビルドした Python が要る（configure の設定を変えたい）	pyenv	PYTHON_CONFIGURE_OPTS で設定を渡せる
Windows で版を切り替えたい	pyenv-win または uv	pyenv 本体は Windows で動かない
チームで同じ版にそろえたい	.python-version をコミット	pyenv・uv のどちらも読む

pyenvでよくあるエラーと直し方

実際に出したエラーの原文と、原因・直し方です。上から、出会いやすい順に並べています。

エラー・症状（原文）	原因	直し方
pyenv: command not found	PATH に pyenv が無い	pyenv init --install 後に exec "$SHELL"
python --version が OS の版のまま	shims より前に別の PATH がある	eval "$(pyenv init --path)" を最後に置く
error: failed to download Python-3.15.0.tar.xz	python.org に届かない（プロキシ等）	https_proxy を設定、またはキャッシュに置く
configure: error: no acceptable C compiler found in $PATH	C コンパイラが無い	build-essential／xcode-select --install
ERROR: The Python ssl extension was not compiled. Missing the OpenSSL lib?	OpenSSL の開発用ファイルが無い	libssl-dev／brew install openssl@3
ModuleNotFoundError: Standard library module '_tkinter' was not found	ビルド時に tk-dev が無かった	tk-dev を入れて pyenv install -f
python-build: definition not found: 3.16.0	その名前の版が無い・pyenv に定義がまだ無い	版名を確かめる、pyenv update
pyenv: version `3.13' not installed	入れていない版を指定した	先に pyenv install 3.13
pyenv: python3.14: command not found	今の版にそのコマンドが無い	複数の版を global に並べる
.python-version の版が入っていないのに動く	system へのすり抜け	pyenv version で確かめて入れる

pyenv: command not found

pyenv を入れただけで、シェルの設定を足していないときに出ます。pyenv init --install を実行し、exec "$SHELL" でシェルを開き直します。設定を足しても出るときは、使っているシェル（bash か zsh か）と、書き足したファイル（.bashrc・.zshrc）が合っているかを確かめます。

cron やシェルスクリプトのような、対話ではないシェルでは .bashrc が読まれません。設定を読まないシェルで python を呼ぶと、OS の Python が動きました。pyenv の版で動かすには、shim か pyenv exec をフルパスで呼びます。

$ bash -c 'python --version'                       # 設定を読まないシェル
Python 3.11.15
$ bash -c '~/.pyenv/shims/python --version'
Python 3.14.8
$ bash -c '~/.pyenv/bin/pyenv exec python --version'
Python 3.14.8

shimsが効かない（python --versionが変わらない）

pyenv の設定より後で、別のツールが PATH の先頭にフォルダを足すと、shims が後ろに回って効かなくなります。 .bashrc で pyenv の設定の後に export PATH="/usr/bin:$PATH" がある状態を再現しました。

$ python --version
Python 3.14.8
$ export PATH="/usr/bin:$PATH"
$ python --version
Python 3.11.15
$ type -a python | head -3
python is /usr/bin/python
python is /home/user/.pyenv/shims/python
python is /usr/bin/python
$ eval "$(pyenv init --path)"
$ python --version
Python 3.14.8
$ echo $PATH | tr : "\n" | head -3
/home/user/.pyenv/shims
/usr/bin
/home/user/.pyenv/bin

type -a python で、shims より前に別の python があることが分かります。pyenv init --path は shims を PATH の先頭へ置き直します。README も、ほかの処理が PATH を書き換えた後に shims を前へ戻す用途として、この使い方を挙げています。

Pythonのダウンロードに失敗する（プロキシ）

python.org からソースを取れないときの出力です。プロキシにつながりを断られ、HTTP 403 が返っています。

$ pyenv install 3.15.0
Downloading Python-3.15.0.tar.xz...
-> https://www.python.org/ftp/python/3.15.0/Python-3.15.0.tar.xz
error: failed to download Python-3.15.0.tar.xz

BUILD FAILED (Ubuntu 24.04 using python-build 2.8.10)

Results logged to /home/user/tmp/python-build.20261017120644.3928.log

Last 10 log lines:
~/tmp/python-build.20261017120644.3928 ~
curl: (22) The requested URL returned error: 403

README は、プロキシを通すときは http_proxy と https_proxy の環境変数を設定するよう書いています。python-build の README によると、~/.pyenv/cache フォルダを作っておくと、ダウンロードしたソースがそこに残ります。同じ名前（例：Python-3.15.0.tar.xz）のファイルを先に置いておくと、ダウンロードせずにそれを使います。 上の成功例は、この方法で置いたソースを使っています。ファイルは pyenv の定義ファイルに書かれた SHA-256 と照合されます。

no acceptable C compiler found（コンパイラが無い）

C コンパイラ（gcc・clang）が無い状態でビルドしたときの出力です。

$ pyenv install 3.15.0
Installing Python-3.15.0...

BUILD FAILED (Ubuntu 24.04 using python-build 2.8.10)

Inspect or clean up the working tree at /home/user/tmp/python-build.20261017120723.10262
Results logged to /home/user/tmp/python-build.20261017120723.10262.log

Last 10 log lines:
checking for --enable-universalsdk... no
checking for --with-universal-archs... no
checking for --with-app-store-compliance... not patching for app store compliance
checking for gcc... no
checking for cc... no
checking for cl.exe... no
checking for clang... no
configure: error: in '/home/user/tmp/python-build.20261017120723.10262/Python-3.15.0':
configure: error: no acceptable C compiler found in $PATH
See 'config.log' for more details

Are the build dependencies for Python correctly installed?
Please consult to the Wiki page for more info.
https://github.com/pyenv/pyenv/wiki#suggested-build-environment

Ubuntu・Debian は build-essential、Fedora は gcc、Mac は xcode-select --install で入ります。

ssl extension was not compiled（OpenSSL が見つからない）

OpenSSL の場所をわざと間違えて（PYTHON_CONFIGURE_OPTS="--with-openssl=/opt/no-such-openssl"）ビルドし、OpenSSL が見つからないときと同じ状態を作りました。ビルドは最後まで進み、5分28秒かかった後の確認で失敗します。 失敗した版はフォルダごと消され、pyenv versions には残りませんでした。

Installing Python-3.15.0...
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import ssl
  File "/home/user/.pyenv/versions/3.15.0/lib/python3.15/ssl.py", line 103, in <module>
    import _ssl             # if we can't import it, let the error propagate
    ^^^^^^^^^^^
ModuleNotFoundError: Standard library module '_ssl' was not found
ERROR: The Python ssl extension was not compiled. Missing the OpenSSL lib?

Please consult to the Wiki page to fix the problem.
https://github.com/pyenv/pyenv/wiki/Common-build-problems


BUILD FAILED (Ubuntu 24.04 using python-build 2.8.10)

Wiki の「Common build problems」は、まず OpenSSL の開発用パッケージ（Ubuntu は libssl-dev、Fedora は openssl-devel）が入っているかを確かめ、標準でない場所にある場合は CPPFLAGS・LDFLAGS か --with-openssl で場所を渡すよう案内しています。同じ形の zlib extension was not compiled は、zlib1g-dev（Ubuntu）を入れて直します。

ビルドは成功したのにtkinterが使えない

pyenv は ssl・zlib などが欠けると失敗にしますが、tkinter や zstd が欠けても「Installed」で終わります。 tk-dev と libzstd-dev が無い状態で 3.15.0 を入れ、標準ライブラリを1つずつ import して確かめました。

import のエラーは、最後の行だけを載せています。

$ pyenv install 3.15.0
Installing Python-3.15.0...
Installed Python-3.15.0 to /home/user/.pyenv/versions/3.15.0

$ python -c "import tkinter"
ModuleNotFoundError: Standard library module '_tkinter' was not found
$ python -c "import compression.zstd"
ModuleNotFoundError: Standard library module '_zstd' was not found

同じ条件で行った ssl の再現のビルドで残ったログ（python-build.*.log）には、configure の時点で次の行が出ていました。

checking for stdlib extension module _tkinter... missing
checking for stdlib extension module _zstd... missing

直し方は、足りないパッケージを入れてから -f で入れ直すことです。

sudo apt install tk-dev libzstd-dev
pyenv install -f 3.15.0

入れ直した後は、tkinter と compression.zstd の import が通りました。

Python 3.15 の _decimal

Python 3.15.0 では、上の手順の後も _decimal（decimal の C 実装）だけが欠けていました。Python 3.15 の「What's New」によると、3.15 から同梱の libmpdec を自動では使わなくなり、OS の libmpdec を使うか、--without-system-libmpdec で同梱版を明示する形に変わっています。Ubuntu 24.04 の apt には libmpdec-dev が無かったため、同梱版を指定して入れ直しました。

$ PYTHON_CONFIGURE_OPTS="--without-system-libmpdec" pyenv install -f 3.15.0
Installing Python-3.15.0...
Installed Python-3.15.0 to /home/user/.pyenv/versions/3.15.0
$ python -c "import _decimal, decimal; print(decimal.__libmpdec_version__)"
2.5.1

_decimal が無くても import decimal は通ります（Python で書かれた実装が使われます）。計算の速さが要る場合は、この入れ直しを行います。

definition not found・version not installed

pyenv が知らない版を指定したときです。名前の一部が合う候補が表示されます。

$ pyenv install 3.16.0
python-build: definition not found: 3.16.0

The following versions contain `3.16.0' in the name:
  3.16.0a1
  3.16.0a1t
  miniconda-3.16.0
  miniconda3-3.16.0

See all available versions with `pyenv install --list'.

If the version you need is missing, try upgrading pyenv:

  cd /home/user/.pyenv && git pull && cd -

新しく出た版が一覧に無いときは、pyenv 自体を更新します（pyenv update、Homebrew なら brew upgrade pyenv）。

入れていない版に切り替えようとしたときは、次のエラーになります。先に pyenv install で入れます。

$ pyenv local 3.13
pyenv: version `3.13' not installed
$ pyenv global 3.13
pyenv: version `3.13' not installed

版付きのコマンドが見つからない

global が 3.15.0 のとき、python3.14 は次のエラーになります。その版を同時に使うには、pyenv global 3.15.0 3.14.8 のように並べます（「複数の版を同時に使う」の節）。

$ python3.14 --version
pyenv: python3.14: command not found

The `python3.14' command exists in these Python versions:
  3.14.8

Note: See 'pyenv help global' for tips on allowing multiple
      Python versions to be found at the same time.

関連記事「ModuleNotFoundErrorの原因と直し方｜No module named」で扱っています。

pyenvのアップデートとアンインストール

pyenv本体を更新する

入れ方	更新のコマンド
Homebrew	brew upgrade pyenv
公式インストーラー	pyenv update（pyenv とプラグインをまとめて更新）
git clone	cd $(pyenv root) && git pull
pyenv-win（インストーラー）	&"${env:PYENV_HOME}\install-pyenv-win.ps1"

新しい Python の版が出たら、pyenv を更新すると pyenv install --list に現れます。

Pythonの版を消す

$ pyenv virtualenv-delete -f tools-3.15
$ pyenv uninstall 3.15.0
pyenv: 3.15.0 uninstalled
$ pyenv versions --bare
3.14.8

pyenv uninstall は確認を求めます（-f で確認なし）。pyenv-virtualenv で作った仮想環境は、もとの版を消すときに一緒に消えます。

pyenvをアンインストールする

README の手順です。

1. 一時的に止めるだけなら、シェルの設定ファイルから pyenv init の行を消します。shims が PATH から外れ、python は OS の Python に戻ります。
2. 完全に消すなら、設定ファイルから pyenv の行をすべて消し、rm -rf $(pyenv root) でフォルダを消します。入れた Python の版もすべて消えます。
3. Homebrew で入れた場合は、最後に brew uninstall pyenv を実行します。

よくある質問

Q. pyenv とは何ですか？ A. 1台の PC に複数の Python の版を入れ、フォルダや端末ごとに切り替えるツールです。shims という入口を PATH の先頭に置いて切り替えます。「pyenvの仕組み（shims）」で説明しています。

Q. pyenv のインストール方法は？ A. Mac は brew install pyenv、Linux は curl -fsSL https://pyenv.run | bash で入れ、pyenv init --install でシェルの設定を足します。Windows は pyenv-win を使います。

Q. pyenv の使い方の基本は？ A. pyenv install 3.15.0 で入れ、pyenv global 3.15.0（全体）か pyenv local 3.14.8（フォルダ）で切り替えます。今の版は pyenv version で確かめます。

Q. pyenv は Windows で使えますか？ A. pyenv 本体は Windows では動きません。Windows では pyenv-win を使うか、WSL の中で pyenv を使います。

Q. pyenv と venv の違いは？ A. pyenv は Python 本体の版を、venv はプロジェクトごとのライブラリを分けます。pyenv で版を決めてから venv を作る組み合わせがよく使われます。

Q. pyenv と uv の違いは？ A. pyenv は Python をソースからビルドして版を切り替えるツールで、uv は Python の取得・仮想環境・パッケージ管理をまとめて行うツールです。どちらも .python-version を読みます。

Q. pyenv install が失敗します。 A. 多くはビルドに要るパッケージの不足です。エラーの最後の行（no acceptable C compiler・ssl extension was not compiled など）を見て、「よくあるエラーと直し方」の表で対応するパッケージを入れます。

まとめ

• pyenv は Python 本体の版を切り替えるツール。パッケージや仮想環境は venv・uv などと組み合わせる。
• 切り替えは shell（端末）→ local（.python-version）→ global（~/.pyenv/version）→ system の順に優先される。
• pyenv install はソースからビルドする。2コアの Linux で 3.15.0 は約3分36秒、402MB だった。
• .python-version に入っていない版が書かれていると、python は黙って OS の Python で動く。pyenv version で確かめる。
• tkinter・zstd が欠けてもビルドは成功扱いになる。依存を足して pyenv install -f で入れ直す。
• shims が効かないときは、type -a python で PATH の順番を見て、pyenv の設定を最後に置く。

参考・出典

確認日はいずれも 2026年10月17日です。

• pyenv（GitHub・README）：https://github.com/pyenv/pyenv
• pyenv COMMANDS.md：https://github.com/pyenv/pyenv/blob/master/COMMANDS.md
• pyenv CHANGELOG：https://github.com/pyenv/pyenv/blob/master/CHANGELOG.md
• pyenv Wiki「Suggested build environment」：https://github.com/pyenv/pyenv/wiki#suggested-build-environment
• pyenv Wiki「Common build problems」：https://github.com/pyenv/pyenv/wiki/Common-build-problems
• python-build README：https://github.com/pyenv/pyenv/blob/master/plugins/python-build/README.md
• pyenv-installer：https://github.com/pyenv/pyenv-installer
• pyenv-win：https://github.com/pyenv-win/pyenv-win
• pyenv-win「Installation」：https://github.com/pyenv-win/pyenv-win/blob/master/docs/installation.md
• Homebrew Formulae「pyenv」：https://formulae.brew.sh/formula/pyenv
• uv「Python versions」：https://docs.astral.sh/uv/concepts/python-versions/
• Python「What's New In Python 3.15」：https://docs.python.org/3.15/whatsnew/3.15.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。