pyenv install が BUILD FAILED になって Python を入れられない

要約

pyenv install は配布バイナリを取ってくるのではなく、その端末で CPython をソースからビルドする。
だから C コンパイラと各標準ライブラリの開発用ヘッダが要る。
足りないと最後に BUILD FAILED だけが目に入るが、直すための情報はその手前にある。

BUILD FAILED (Ubuntu 24.04 using python-build 2.4.19)
 
ERROR: The Python ssl extension was not compiled. Missing the OpenSSL lib?

BUILD FAILED の行だけを検索しても答えは出ない。どの extension が compiled されなかったかを読むと、入れるべきパッケージが一意に決まる。

よくある原因

1. 開発用ヘッダの不足: ssl なら OpenSSL、zlib なら zlib、_ctypes なら libffi、readline なら readline の -dev / -devel パッケージが必要になる。
   ランタイムだけ入っていてもヘッダが無ければビルドできない。
2. ビルドツール自体が無い: Common build problems（新しいタブで開く）↗ が最初に挙げているとおり、make やコンパイラが未導入だと何も始まらない。
3. macOS の OpenSSL の位置: Homebrew の OpenSSL は既定の探索パスに置かれないため、明示的にヘッダとライブラリの場所を渡す必要がある。
4. /tmp が noexec: 共有サーバーや強化された環境で起きる。
   ビルド中に一時ディレクトリへ置いたスクリプトを実行できず、原因の分かりにくい失敗になる。
5. pyenv 本体が古い: 新しいバージョンのビルド定義は pyenv の更新で配られる。
   定義が無ければ、そもそもそのバージョンを選べない。

解決策

1. 不足しているライブラリを入れる

Ubuntu / Debian 系は Suggested build environment（新しいタブで開く）↗ の一覧をそのまま使う。

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
  libreadline-dev libsqlite3-dev libffi-dev liblzma-dev tk-dev

入れ終わったら、失敗したバージョンをもう一度 pyenv install する。
途中まで作られたディレクトリは自動で作り直される。

2. macOS でヘッダの場所を渡す

CPPFLAGS="-I$(brew --prefix openssl)/include" \
LDFLAGS="-L$(brew --prefix openssl)/lib" \
pyenv install -v 3.12.4

-v を付けると configure と make の出力がそのまま流れるので、どの検査で落ちたかを追える。

3. 一時ディレクトリを変える

mkdir -p ~/tmp
TMPDIR=~/tmp pyenv install 3.12.4

mount | grep noexec に /tmp が出るなら、この回避が効く。

4. pyenv を更新する

cd "$(pyenv root)" && git pull
pyenv install --list | grep -E '^  3\.13'

--list に目的のバージョンが出てこないなら、原因はビルド環境ではなく定義の古さである。

5. ログ全体を残して読む

pyenv install 3.12.4 2>&1 | tee /tmp/pyenv-build.log
grep -n "not compiled\|error:" /tmp/pyenv-build.log

失敗が複数のライブラリにまたがることも多い。
1 個直しては再実行、を繰り返すより、まとめて拾ったほうが速い。