pip install で wheel のビルドに失敗する

wheel が公開されていない sdist は手元でビルドが走るため、C / Rust 拡張に必要なコンパイラやヘッダが揃っていないと失敗する。
ビルドツールチェインを入れる、wheel が出ている Python に合わせる、setuptools / pip を更新するで切り分ける。

#pip #wheel #build #c-extension #rust

公開: 2026-05-15更新: 2026-08-31

実行例あり（2026-08-09 に実環境で検証）

要約

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 cryptography

cryptography / 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 仕様の公式ドキュメント（新しいタブで開く））。

実行例

実際に上記の手順を python:3.12-slim（Debian GNU/Linux 13 trixie）で動かすと、gcc 不在の状態では error: [Errno 2] No such file or directory: 'gcc' とともにビルドが終了コード 1 で失敗し、apt-get install -y gcc で gcc 14.2.0 を導入した後は wheel の生成とインストールが正常に完了する流れを確認できる。

$ which gcc
which gcc の終了コード: 1（1 ならコンパイラ不在）

$ pip install --no-cache-dir .
Processing /tmp/tmp.4gjKhvZfoj/demoext
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  Getting requirements to build wheel: finished with status 'done'
  Preparing metadata (pyproject.toml): started
  Preparing metadata (pyproject.toml): finished with status 'done'
Building wheels for collected packages: demoext
  Building wheel for demoext (pyproject.toml): started
  Building wheel for demoext (pyproject.toml): finished with status 'error'
  error: subprocess-exited-with-error
  
  × Building wheel for demoext (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [6 lines of output]
      running bdist_wheel
      running build
      running build_ext
      building 'demoext' extension
      gcc -fno-strict-overflow -Wsign-compare -DNDEBUG -g -O3 -Wall -fPIC -I/usr/local/include/python3.12 -c demoext.c -o build/temp.linux-x86_64-cpython-312/demoext.o
      error: [Errno 2] No such file or directory: 'gcc'
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for demoext
Failed to build demoext
 
[notice] A new release of pip is available: 25.0.1 -> 26.2.1
[notice] To update, run: pip install --upgrade pip
ERROR: Failed to build installable wheels for some pyproject.toml based projects (demoext)
pip の終了コード: 1

$ apt-get install -y gcc
apt-get の終了コード: 0

$ gcc --version
gcc (Debian 14.2.0-19) 14.2.0
Copyright (C) 2024 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

$ pip install --no-cache-dir .
Processing /tmp/tmp.4gjKhvZfoj/demoext
  Installing build dependencies: started
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: started
  Getting requirements to build wheel: finished with status 'done'
  Preparing metadata (pyproject.toml): started
  Preparing metadata (pyproject.toml): finished with status 'done'
Building wheels for collected packages: demoext
  Building wheel for demoext (pyproject.toml): started
  Building wheel for demoext (pyproject.toml): finished with status 'done'
  Created wheel for demoext: filename=demoext-0.1.0-cp312-cp312-linux_x86_64.whl size=756

— 2026-08-09 時点の出力

検証環境

検証日: 2026-08-09
実行環境: python:3.12-slim

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

要約