pip install で wheel のビルドに失敗する
wheel が公開されていない sdist は手元でビルドが走るため、C / Rust 拡張に必要なコンパイラやヘッダが揃っていないと失敗する。
ビルドツールチェインを入れる、wheel が出ている Python に合わせる、setuptools / pip を更新するで切り分ける。
公開: 更新:
要約
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 仕様の公式ドキュメント（新しいタブで開く））。
実行例
実際に上記の手順を 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 時点の出力