🔧

【解決】pyenv install が ld: symbol not found で失敗する問題の対処（Apple Silicon編）

に公開
Python
Homebrew
macOS
pyenv
Apple silicon
tech

育休中でしばらく開発から離れていましたが、久しぶりに環境を触ることに。
macOS のアップデートから始まり、ライブラリやツールの更新を進めていたところ
pyenv install 3.13.5 でエラーが発生。

この記事では、その原因と解決までの記録を残します。

✅ 環境

  • MacBook（Apple M1）
  • macOS Sequoia 15.5

エラー内容

pyenv install 3.13.5 を実行したところ、以下のようなエラーが表示されてインストールが失敗しました。

ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [Programs/_freeze_module] Error 1

リンク時に libintl_* 系のシンボルが見つからないのが原因で、gettext まわりの問題が疑われました。

解決に至らなかった対処

まずはチャッピーに相談。

この `pyenv install 3.13.5` のビルド失敗は、再び libintl（gettext）のシンボルが見つからず clang がリンクエラーを出していることが原因です。
先ほど紹介した CPPFLAGS / LDFLAGS の設定がまだシェルに反映されていないか、効いていない状態です。

とのこと。
そこで、明示的に下記のようにする指示が。

export CPPFLAGS="-I$(brew --prefix)/include -I$(brew --prefix gettext)/include"
export LDFLAGS="-L$(brew --prefix)/lib -L$(brew --prefix gettext)/lib"
export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$(brew --prefix gettext)/lib/pkgconfig"

…が、状況は改善せず😢

根本的な原因

pyenv install 3.13.5 実行時に発生した以下のエラー：

ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1

これは、Apple Silicon（M1/M2/M3）Mac 上で Rosetta（Intel）環境の Homebrew を使用していた ことが原因でした。

brew --prefix を確認してみると

$ brew --prefix
/usr/local

本来 Apple Silicon では /opt/homebrew 以下にインストールされるはずですが、/usr/local となっていたため、x86_64（Intel）版 Homebrew が使われている状態。

ARM Mac 上で Intel 向けパッケージをビルドに使うと、Python のビルド中にライブラリのリンクエラーが発生しやすくなります。

# システムが ARM ネイティブか確認
arch
# => arm64

# ARM Homebrew がインストールされているか確認
ls /opt/homebrew
# => 存在すれば OK
# もし /opt/homebrew が存在しない場合は、インストール：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# ARM Homebrew を使う設定（.zshrc などに追記推奨）
eval "$(/opt/homebrew/bin/brew shellenv)"

別のエラーが出た

pyenv install 3.13.5 を再試行すると、今度は別のエラーが発生しました。

install: Modules/_blake2.cpython-313-darwin.so: No such file or directory

これは、Intel (x86) 向けの Homebrew パッケージが混在していたことが原因です。

Apple Silicon (ARM64) 上で Intel 向けライブラリを使うと、Python ビルド中にアーキテクチャが合わず、.so（共有ライブラリ）ファイルのインストールに失敗します。

このように、異なるアーキテクチャのパッケージが混ざっていると、原因不明のビルドエラーが頻発するため注意が必要です。

解決方法

問題の原因は、Intel 版と Apple Silicon 版の Homebrew パッケージが混在していたことでした。

解決のため、一旦 Intel 版 Homebrew のパッケージをすべてアンインストールしました。

/usr/local/Homebrew/bin/brew uninstall --force $(/usr/local/Homebrew/bin/brew list)

その後、Apple Silicon 版 Homebrew 環境で pyenv install 3.13.5 を実行したところ…

pyenv install 3.13.5

ビルドは無事成功しました！

ポイントまとめ

  • ARM ネイティブの Homebrew (/opt/homebrew) を使うこと
  • Intel 版 Homebrew (/usr/local) のパッケージを混ぜないこと
  • eval "$(/opt/homebrew/bin/brew shellenv)" を .zshrc に書いて環境変数を正しく設定すること

これで Apple Silicon Mac 上でも pyenv を使った Python ビルドが安定します。

まとめ

  • M1 Mac で pyenv install が失敗した原因は、Intel 版 Homebrew と Apple Silicon 版 Homebrew の混在だった
  • brew --prefix で確認して、ARM 用 Homebrew は /opt/homebrew、Intel 用は /usr/local にある
  • .zshrc に eval "$(/opt/homebrew/bin/brew shellenv)" を書いて、ARM ネイティブ環境を優先させる
  • Intel 版 Homebrew のパッケージを全部削除したら、ビルドが成功した
  • M1 Mac で Python や他のソフトをビルドするときは、アーキテクチャの混在に注意

エンジニアとしての勘を取り戻している最中なので、チャッピーにはかなり助けられました。
（にしても、Apple Silicon 版の Homebrewまで辿り着くのに時間がかかった。。。）

Discussion