pip install で wheel のビルドに失敗する
wheel が公開されていない sdist は手元でビルドが走るため、C / Rust 拡張に必要なコンパイラやヘッダが揃っていないと失敗する。
ビルドツールチェインを入れる、wheel が出ている Python に合わせる、setuptools / pip を更新するで切り分ける。
#pip#wheel#build#c-extension#rust
要約
error: command 'gcc' failed Building wheel for X (pyproject.toml) did not run successfully. は、wheel が公開されていない sdist を手元でビルドしようとして 必要なコンパイラ / ヘッダが揃っていない 状態。
OS の開発ツール、Python 開発ヘッダ、Rust ツールチェインのいずれかを入れれば多くが解消する。
先に wheel が出ている Python に切り替えるのが最短のケースも多い。
よくある原因
- コンパイラ不在: Linux なら gcc、macOS は Xcode Command Line Tools、Windows は VS Build Tools が無い。
- 開発ヘッダ不足:
Python.hが見つからない場合はpython3-dev（Debian/Ubuntu）やpython3-devel（RHEL 系）が必要。 - Rust 拡張: 最近の暗号系（
cryptography等）は Rust が必須。error: can't find Rust compilerで気付く。 - system ライブラリ不足:
libssl-dev/libffi-dev/libxml2-devなどのヘッダが無く、リンク段階で失敗する。 - 古い pip / setuptools: PEP 517 の
build-system指定を読めず、build バックエンドの呼び出しで詰まる。
解決策
1. OS の開発ツールを入れる
# Debian / Ubuntu
sudo apt-get install build-essential python3-dev libssl-dev libffi-dev
# macOS
xcode-select --install
# Windows
# Visual Studio Build Tools の Desktop development with C++ を選んでインストール2. Rust ツールチェインを入れる
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"
pip install cryptographycryptography / pydantic-core / orjson などは Rust 拡張を含む。
rustup で stable を入れるのが標準的（pip install のドキュメント でも sdist のビルドツール必要性に触れている）。
3. pip と setuptools を更新
python -m pip install -U pip setuptools wheel古い pip だと pyproject.toml の build-system を正しく読めず、backend-path 不在で落ちることがある。
4. wheel が出ている Python に切り替え
pyenv install 3.11.9
pyenv local 3.11.9
pip install pandas最新 Python（リリース直後）は wheel がまだ揃っておらず、sdist ビルドに回ることが多い。
PyPI のパッケージページで cp311 等の wheel ファイル名が公開されているマイナーに合わせるのが手堅い（sdist 仕様の公式ドキュメント）。