できない.dev

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

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

公開: 更新:

症状できない · exit 1
which gcc
解決後できた · exit 0
apt-get install -y gcc

2026-08-09 に python:3.12-slim で実際に打って取った出力。検証環境の詳細

要約

error: command 'gcc' failed Building wheel for X (pyproject.toml) did not run successfully. は、wheel が公開されていない sdist を手元でビルドしようとして、必要なコンパイラ / ヘッダが揃っていないときに出る。
OS の開発ツール、Python 開発ヘッダ、Rust ツールチェインのいずれかを入れれば多くが解消する。
先に wheel が出ている Python に切り替えたほうが早いケースも多い。

実行例

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
$ echo $?
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)
$ echo $?
1
$ apt-get install -y gcc
$ echo $?
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

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

解決策

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 のビルドを避けられる(sdist 仕様の公式ドキュメント(新しいタブで開く))。

よくある原因

  1. コンパイラが入っていない。
    Linux なら gcc、macOS は Xcode Command Line Tools、Windows は VS Build Tools が無い。
  2. 開発ヘッダが足りない。
    Python.h が見つからない場合は、python3-dev(Debian/Ubuntu)や python3-devel(RHEL 系)が必要になる。
  3. Rust 拡張を含むパッケージをビルドしている。
    最近の暗号系(cryptography 等)は Rust が必須で、error: can't find Rust compiler で気付く。
  4. system ライブラリが足りない。
    libssl-dev / libffi-dev / libxml2-dev などのヘッダが無く、リンク段階で失敗する。
  5. pip / setuptools が古い。
    PEP 517 の build-system 指定を読めず、build バックエンドの呼び出しで詰まる。