subprocess-exited-with-errorの原因9つと直し方｜pip

この記事で実際に動かしたもの：自分の venv の中で、C 拡張・Cython・Rust の小さな自作パッケージと、PyPI の numpy・psycopg2 を pip で入れ、コンパイラを PATH から外した環境でエラーを起こし、原文と直したあとの出力を記録しました。

flowchart TD
    A[pip install] --> B{合う wheel が<br>PyPI にある?}
    B -->|ある| OK[そのまま入る]
    B -->|無い| S[ソース sdist を<br>ダウンロード]
    S --> C[4つの段階でビルド<br>依存・要るもの・<br>メタデータ・wheel]
    C -->|成功| OK
    C -.->|どこかで失敗| X[subprocess-<br>exited-with-error]

やりたいことごとに、いちばん早い方法を先にまとめます。

確認環境：Ubuntu 24.04.5 LTS（Linux カーネル 6.18、x86_64）の上で、Python 3.13.18 と 3.11.18 の venv を作業用のフォルダーに作り、pip 26.2.2 を主に、比較のため pip 20.2.4・21.3.1・22.0・24.0・25.0・26.3 を同じ venv に入れ替えて使いました。コンパイラ（gcc 13.3.0）はホストから消さず、env -i で環境変数を空にしてから PATH を「venv の bin ＋最小限のコマンド」だけにして隠しました。pip のキャッシュと一時フォルダーも作業用のフォルダーに向けています。ビルドの中で使われた setuptools は 84.2.1、Cython は 3.3.1 です。PyPI からはダウンロードだけを行い、アップロード・アカウント作成はしていません。出力のパスは読みやすさのため作業用のフォルダーを /work に置き換え、長い gcc のオプションは一部を「…」で省いています。Windows・Mac の手順は手元で動かせないため、Python Wiki（WindowsCompilers）、Microsoft（Build Tools for Visual Studio）、Python 開発者ガイド、pip・Python Packaging User Guide・psycopg の公式ドキュメントで確かめた範囲だけを書いています（確認日 2026年11月6日）。

error: subprocess-exited-with-errorとは（エラー文の読み方）

この節では、エラー全体のどこに原因が書かれているのか、どの行を読めばよいのかが分かります。

pip はパッケージをソースからビルドするとき、自分では組み立てず、setuptools・meson-python・maturin などの「ビルドバックエンド」を別のプロセスとして起動します。その子プロセスが 0 以外の終了コードで終わると、pip は error: subprocess-exited-with-error と表示します。pip 自身が出す次の1行が、そのことをはっきり書いています。

note: This error originates from a subprocess, and is likely not a problem with pip.

つまり「pip の不具合ではなく、ビルドの中で何かが足りない」という意味です。次は、コンパイラを隠した環境で自作の C 拡張パッケージ（cdemo）を入れたときの原文全体です。

$ pip install /work/pkgs/cdemo
Processing /work/pkgs/cdemo
  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: cdemo
  Building wheel for cdemo (pyproject.toml): started
  Building wheel for cdemo (pyproject.toml): finished with status 'error'
  error: subprocess-exited-with-error

  × Building wheel for cdemo (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [6 lines of output]
      running bdist_wheel
      running build
      running build_ext
      building 'cdemo' extension
      x86_64-linux-gnu-gcc -fno-strict-overflow -Wsign-compare -DNDEBUG -g -O2 … -fPIC -I/work/v313/include -I/usr/include/python3.13 -c src/cdemo.c -o build/temp.linux-x86_64-cpython-313/src/cdemo.o
      error: [Errno 2] No such file or directory: 'x86_64-linux-gnu-gcc'
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for cdemo
Failed to build cdemo
error: failed-wheel-build-for-install

× Failed to build installable wheels for some pyproject.toml based projects
╰─> cdemo

読む順番は、次の3か所です。

出力が長くて流れてしまうときは、pip install --log pip.log 〇〇 で全文をファイルに残せます。手元では1,651行のログの1,627行目に fatal error: zstd.h: No such file or directory が残っていました。-v を付けると画面にも詳しく出ます。

Failed building wheelはどの段階か（4つの段階の見分け方）

この節では、「×」の行に出る4つの段階の名前と、それぞれで疑うべき原因が分かります。

pip の公式ドキュメント（Build System Interface）によると、pip はソースから入れるとき、隔離した一時環境にビルド依存を入れ、ビルドバックエンドの関数を順に呼びます。この記事の再現では、4つの段階すべてで subprocess-exited-with-error を出せました。

どの段階でも最後に出る1行は pip の版と段階で変わります。pip 26.2 では error: failed-wheel-build-for-install（ビルドで失敗）、error: metadata-generation-failed（メタデータで失敗）、ERROR: Failed to build '〇〇' when getting requirements to build wheel などが出ました。検索するときは最後の1行ではなく、[N lines of output] の中の行で探すほうが早く当たります。

subprocess-exited-with-errorの原因一覧（症状→原因→直し方）

この節では、この記事で再現した9つの原因と、枠の中に出る決まり文句、直し方の対応が一覧で分かります。

どの原因でも、最初の手は「ビルドしなくて済む道があるか」を確かめることです。直す順番は次のとおりです。

1. 1pip を新しくする以前の版の pip は、新しい形式の wheel を選べずソースに回る
2. 2wheel のある版を選ぶ--only-binary=:all: で「ビルドしないと入らないか」を数秒で確かめる
3. 3Python の版をパッケージに合わせるvenv を作り直す。新しすぎる Python はまだ wheel が無いことがある
4. 4ビルドツールを入れるコンパイラ・ヘッダー・設定ツール・Rust を、エラーの文言どおりに足す
5. 5ビルド依存を直す自分のパッケージなら requires、他人のなら --build-constraint

原因1：コンパイラが無い（gcc・cc が見つからない）

この節では、C コンパイラが無いときに setuptools と meson で出る文言の違いと、直したあとの出力が分かります。

setuptools で C 拡張をビルドするパッケージでは、冒頭の例のように error: [Errno 2] No such file or directory: 'x86_64-linux-gnu-gcc' と出ます。呼ぶコンパイラの名前は Python のビルド設定で決まっており、次の1行で確かめられます。

$ python -c 'import sysconfig; print(sysconfig.get_config_var("CC"))'
x86_64-linux-gnu-gcc

numpy・scipy のように meson-python を使うパッケージでは、同じ「コンパイラが無い」でも段階と文言が変わり、Preparing metadata の段階で止まります。

$ pip install numpy==1.26.4
Collecting numpy==1.26.4
  Downloading numpy-1.26.4.tar.gz (15.8 MB)
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: finished with status 'done'
  Installing backend dependencies: finished with status 'done'
  Preparing metadata (pyproject.toml): finished with status 'error'
  error: subprocess-exited-with-error

  × Preparing metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [20 lines of output]
      The Meson build system
      Version: 1.2.99
      Project name: NumPy
      Project version: 1.26.4

      ../meson.build:1:0: ERROR: Unknown compiler(s): [['cc'], ['gcc'], ['clang'], ['nvc'], ['pgcc'], ['icc'], ['icx']]
      The following exception(s) were encountered:
      Running `cc --version` gave "[Errno 2] No such file or directory: 'cc'"
      Running `gcc --version` gave "[Errno 2] No such file or directory: 'gcc'"
      Running `clang --version` gave "[Errno 2] No such file or directory: 'clang'"
      ...
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> numpy

PATH に gcc を戻すと、同じ自作パッケージは数秒でビルドでき、import して動きました。

$ pip install /work/pkgs/cdemo
  Building wheel for cdemo (pyproject.toml): finished with status 'done'
  Created wheel for cdemo: filename=cdemo-0.1.0-cp313-cp313-linux_x86_64.whl size=8049
Successfully built cdemo
Successfully installed cdemo-0.1.0

$ python -c 'import cdemo; print(cdemo.add(2, 3))'
5

ただし numpy の例は、コンパイラを入れるより「Python 3.13 に wheel がある numpy を選ぶ」ほうが正解です（原因5）。コンパイラを入れるのは、wheel がどの版にも無いパッケージか、自分でソースを変えてビルドしたいときです。

原因2・3：ヘッダーが無い（Python.h・zstd.h など）

この節では、コンパイラはあるのにヘッダーファイルが足りないときの文言と、入れるべきパッケージの名前の探し方が分かります。

C 拡張は、Python 自身のヘッダー（Python.h）と、包んでいる外部ライブラリのヘッダー（zstd.h・libpq-fe.h・ffi.h など）を読み込んでコンパイルします。どちらかが無いと、gcc が fatal error: 〇〇.h: No such file or directory を出します。zstd を使う自作パッケージで起こした原文です。

  × Building wheel for zdemo (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [10 lines of output]
      building 'zdemo' extension
      x86_64-linux-gnu-gcc … -fPIC -I/work/v313/include -I/usr/include/python3.13 -c src/zdemo.c -o build/temp.linux-x86_64-cpython-313/src/zdemo.o
      src/zdemo.c:2:10: fatal error: zstd.h: No such file or directory
          2 | #include <zstd.h>
            |          ^~~~~~~~
      compilation terminated.
      error: Command '['x86_64-linux-gnu-gcc', … ]' returned non-zero exit status 1.
      [end of output]

Python.h は、この環境では /usr/include/python3.13 にヘッダーが入っているため pip の中では再現できませんでした。代わりに、Python のヘッダーの場所（-I/usr/include/python3.13）を渡さずに同じファイルを gcc でコンパイルすると、同じ形の文言になります。

$ gcc -fPIC -c src/cdemo.c -o x.o
src/cdemo.c:1:10: fatal error: Python.h: No such file or directory
    1 | #include <Python.h>
      |          ^~~~~~~~~~
compilation terminated.

$ python3.13-config --includes
-I/usr/include/python3.13 -I/usr/include/python3.13

直し方は、ヘッダーを含む「開発用パッケージ」を入れることです。Debian・Ubuntu では名前の末尾が -dev、Fedora などでは -devel です。psycopg の公式ドキュメントも、Python.h には python3-dev、libpq-fe.h には libpq-dev が要ると書いています。

手元では、ホストの設定を変えないために libzstd-dev を apt-get download で取得して作業用のフォルダーに展開し、場所を CFLAGS・LDFLAGS で渡しました。ふだんは sudo apt install libzstd-dev で入れれば、この指定は要りません。

$ apt-get download libzstd-dev
$ dpkg-deb -x libzstd-dev_1.5.5+dfsg2-2build1.1_amd64.deb /work/deb/root
$ CFLAGS="-I/work/deb/root/usr/include" \
  LDFLAGS="-L/work/deb/root/usr/lib/x86_64-linux-gnu" \
  pip install /work/pkgs/zdemo
Successfully built zdemo
Successfully installed zdemo-0.1.0
$ python -c 'import zdemo; print(zdemo.add(40, 2))'
42

原因4：pg_configなど設定ツールが無い（psycopg2）

この節では、ヘッダーより前に「設定ツール」を探すパッケージで出る文言と、psycopg2 と psycopg2-binary の使い分けが分かります。

psycopg2 は、PostgreSQL の pg_config コマンドでヘッダーとライブラリの場所を調べてからビルドします。pg_config が PATH に無いと、コンパイルより前の Getting requirements to build wheel の段階で止まります。

$ pip install psycopg2
Collecting psycopg2
  Downloading psycopg2-2.9.13.tar.gz (378 kB)
  Installing build dependencies: finished with status 'done'
  Getting requirements to build wheel: finished with status 'error'
  error: subprocess-exited-with-error

  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [34 lines of output]
      running egg_info
      writing psycopg2.egg-info/PKG-INFO

      Error: pg_config executable not found.

      pg_config is required to build psycopg2 from source.  Please add the directory
      containing pg_config to the $PATH or specify the full executable path with the
      option:

          python setup.py build_ext --pg-config /path/to/pg_config build ...

      or with the pg_config option in 'setup.cfg'.

      If you prefer to avoid building psycopg2 from source, please install the PyPI
      'psycopg2-binary' package instead.
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed to build 'psycopg2' when getting requirements to build wheel

PyPI の配布ファイルを数えると、psycopg2 2.9.13 の wheel は Windows（win_amd64）向けだけで、Linux・Mac は必ずソースからのビルドになります。psycopg2-binary は各 OS 向けの wheel を持っているため、ビルドせずに入りました。

$ pip install --only-binary=:all: psycopg2
ERROR: Could not find a version that satisfies the requirement psycopg2 (from versions: none)
ERROR: No matching distribution found for psycopg2

$ pip install psycopg2-binary
Successfully installed psycopg2-binary-2.9.13       ← 0.7 秒
$ python -c 'import psycopg2; print(psycopg2.__version__)'
2.9.13 (dt dec pq3 ext lo64)

原因5：Pythonが新しすぎてwheelが無い（Failed building wheelの代表例）

この節では、いちばん多い「自分の Python の版向けの wheel がまだ無い」状態の見分け方と、ビルドせずに直す方法が分かります。

原因1の numpy 1.26.4 の例は、実はコンパイラより前の問題です。PyPI の配布ファイルを Python の版ごとに数えると、numpy 1.26.4 には cp313（Python 3.13 向け）の wheel が1つもありません。pip は合う wheel が無いため、ソース（tar.gz）を落としてビルドしに行き、失敗しました。

$ python wheels.py numpy 1.26.4
numpy 1.26.4 {'cp310': 8, 'cp311': 8, 'cp312': 8, 'cp39': 8, 'pp39': 3, 'sdist': 1}
$ python wheels.py numpy 2.1.0
numpy 2.1.0 {'cp310': 10, 'cp311': 9, 'cp312': 10, 'cp313': 18, 'pp310': 4, 'sdist': 1}

数えるのに使ったのは、PyPI の JSON API（https://pypi.org/pypi/名前/版/json）を読むだけの短いスクリプトです。PyPI のページの「Download files」を見ても同じことが分かります。

import json, sys, urllib.request, collections
name, ver = sys.argv[1], sys.argv[2]
d = json.load(urllib.request.urlopen(f"https://pypi.org/pypi/{name}/{ver}/json"))
c = collections.Counter()
for f in d["urls"]:
    fn = f["filename"]
    c[fn.split("-")[2] if fn.endswith(".whl") else "sdist"] += 1
print(name, ver, dict(sorted(c.items())))

いちばん早い確かめ方は --only-binary です。「ソースは使わない」と指示すると、ビルドで長く待たずに、Python 3.13 で選べる版の一覧がすぐ出ます。

$ pip install --dry-run --only-binary=:all: numpy==1.26.4
ERROR: Could not find a version that satisfies the requirement numpy==1.26.4 (from versions: 2.1.0, 2.1.1, 2.1.2, 2.1.3, 2.2.0, ..., 2.5.3, 2.5.4)
ERROR: No matching distribution found for numpy==1.26.4

$ pip install --dry-run --ignore-installed --only-binary=:all: --python-version 3.12 --target /work/tt numpy==1.26.4
  Downloading numpy-1.26.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (61 kB)
Would install numpy-1.26.4

$ pip install --only-binary=:all: "numpy>=2.1"
Downloading numpy-2.5.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (16.7 MB)
Successfully installed numpy-2.5.4

直し方は2つです。requirements.txt の numpy==1.26.4 のような固定を外して wheel のある版にするか、固定を変えられないなら Python 3.12 の venv を作り直します。--prefer-binary は「wheel があればそちらを選ぶ」だけなので、numpy<2 のようにどの候補にも wheel が無い指定では、手元でもやはり tar.gz を落としに行きました。

Python の版を切り替える方法は、関連記事「pyenvとは｜インストール・使い方・仕組みとエラーの直し方」で扱っています。venv の作り直しの手順は、関連記事「Python venvの使い方｜作成・有効化コマンド早見表と有効化できない時の直し方」で扱っています。

原因6：pipが以前の版でwheelを選べない

この節では、wheel は PyPI にあるのに、pip の版が前のものだとソースに回ってしまう例と、エラー文の違いが分かります。

wheel のファイル名には、動く OS の条件（manylinux_2_28 など）が入っています。以前の版の pip はこの新しい書き方を知らないため、合う wheel が無いと判断してソースを落とします。Python 3.11 の venv に pip 20.2.4 を入れ、numpy 2.3.5（Linux 向けの cp311 の wheel は manylinux_2_27・2_28 の形式だけ）を入れた原文です。

$ pip --version
pip 20.2.4 from /work/vold/lib/python3.11/site-packages/pip (python 3.11)
$ pip install numpy==2.3.5
Collecting numpy==2.3.5
  Downloading numpy-2.3.5.tar.gz (20.6 MB)
  Installing build dependencies: started
  ...
    Preparing wheel metadata: finished with status 'error'
    ERROR: Command errored out with exit status 1:
     command: /work/vold/bin/python3.11 /work/vold/lib/python3.11/site-packages/pip/_vendor/pep517/_in_process.py prepare_metadata_for_build_wheel /work/tmp/tmpbpsy100h
         cwd: /work/tmp/pip-install-1a7e6gp_/numpy
    Complete output (20 lines):
    ...
    ../meson.build:1:0: ERROR: Unknown compiler(s): [['cc'], ['gcc'], ['clang'], ['nvc'], ['pgcc'], ['icc'], ['icx']]
    ----------------------------------------
ERROR: Command errored out with exit status 1: ... Check the logs for full command output.

pip を新しくすると、同じ指定で wheel が選ばれ、ビルドせずに入りました。失敗まで56秒かかっていたものが、2.5秒で終わっています。

$ python -m pip install -U pip
$ pip --version
pip 26.3 from /work/vold/lib/python3.11/site-packages/pip (python 3.11)
$ pip install numpy==2.3.5
  Downloading numpy-2.3.5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.metadata (62 kB)
Downloading numpy-2.3.5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (16.9 MB)
Successfully installed numpy-2.3.5

自分の pip がどの wheel を選べるかは、pip debug --verbose の Compatible tags で見られます。手元の pip 26.2 では1,147個のタグが並び、先頭は cp313-cp313-manylinux_2_39_x86_64 でした。pip の版を上げるときは、pip ではなく python -m pip で、使っている Python に結びついた pip を確実に動かします。

同じエラーでも、pip の版で見た目が変わります。自作の cdemo をコンパイラ無しで入れて比べた結果です。

「Command errored out with exit status 1」と「subprocess-exited-with-error」は、同じ失敗の以前の書き方と今の書き方です。ネットの記事で文言が違っても、枠の中の原因の行が同じなら同じ直し方が当てはまります。

原因7・8：pyproject.tomlのビルド依存（書き漏れ・新しい版で壊れる）

この節では、ビルド用の隔離環境で起きる2つの失敗と、--no-build-isolation・--build-constraint の使いどころが分かります。

pip は既定で、ソースのビルドごとに使い捨ての環境を作り、pyproject.toml の [build-system] requires に書かれたものだけを入れます（ビルドの隔離）。venv に Cython が入っていても、requires に書いていなければビルドの中からは見えません。setup.py で Cython を import する自作パッケージで起こした原文です。

[build-system]
requires = ["setuptools>=77"]          # Cython を書き忘れている
build-backend = "setuptools.build_meta"

  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [20 lines of output]
      Traceback (most recent call last):
        ...
        File "/work/tmp/pip-build-env-mm2j6x7z/overlay/lib/python3.13/site-packages/setuptools/build_meta.py", line 317, in run_setup
          exec(code, locals())  # noqa: S102 # exec is intentional here
        File "<string>", line 2, in <module>
      ModuleNotFoundError: No module named 'Cython'
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed to build 'file:///work/pkgs/cydemo' when getting requirements to build wheel

パスの pip-build-env-…/overlay が、隔離された一時環境です。requires に "Cython>=3" を足すと5.6秒でビルドでき、Cython で書いた関数が動きました。他人のパッケージで pyproject.toml を直せないときは、ビルドに要るものを自分の venv に入れて、隔離を外します。

$ pip install /work/pkgs/cydemo          # requires に Cython を足したあと
Successfully installed cydemo-0.1.0
$ python -c 'import fastsum; print(fastsum.fsum(10**6))'
499999500000

$ pip install Cython setuptools           # 直せない場合
$ pip install --no-build-isolation /work/pkgs/cydemo
Successfully installed cydemo-0.1.0

もう1つは、requires に書かれたものが入らない場合です。版の指定が存在しない範囲だと、最初の installing build dependencies で止まります。

  Installing build dependencies: finished with status 'error'
  error: subprocess-exited-with-error

  × installing build dependencies did not run successfully.
  │ exit code: 1
  ╰─> [3 lines of output]
      ERROR: Ignored the following yanked versions: 51.1.0.post20201221, 59.1.0, ...
      ERROR: Could not find a version that satisfies the requirement setuptools>=999 (from versions: 0.6b1, ..., 84.2.0, 84.2.1)
      ERROR: No matching distribution found for setuptools>=999
      [end of output]
ERROR: Failed to build 'file:///work/pkgs/bdemo' when installing build dependencies

逆に、requires が setuptools のように版を決めていないと、ビルドのたびに最新版が入ります。新しい setuptools が以前の書き方を受け付けなくなると、昨日まで入っていたパッケージが急に失敗します。pip 25.3 で加わった --build-constraint（pip の変更履歴）を使うと、ビルド用の環境に入る版だけを固定できます。手元では setuptools<78 を指定すると、ビルドの中に 77.0.3 が入りました。

$ echo 'setuptools<78' > build-constraints.txt
$ pip install -v --build-constraint build-constraints.txt /work/pkgs/bdemo
  Downloading setuptools-77.0.3-py3-none-any.whl (1.3 MB)
  Successfully installed setuptools-77.0.3
Successfully installed bdemo-0.1.0

pip 公式ドキュメントでも、--no-build-isolation を使うと PEP 518 のビルド依存は自分で入れておく必要がある、と書かれています。隔離を外すのは、何が要るか分かっているときだけにします。

pyproject.toml の書き方とビルドの流れは、関連記事「PyPI とは｜パッケージ公開の手順・pyproject.toml・エラーを実演」で扱っています。

原因9：Rustが要るパッケージ（maturin・setuptools-rust）

この節では、Rust で書かれた拡張（pydantic-core・tokenizers・cryptography など）をソースから入れるときに出る文言が分かります。

Rust の拡張はビルドバックエンドに maturin か setuptools-rust を使い、ビルドには Rust のコンパイラ（rustc と cargo）が要ります。cargo を PATH から外した環境で、maturin を使う自作パッケージを入れたところ、Preparing metadata の段階で次のように出ました。

  × Preparing metadata (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [90 lines of output]
      Python reports SOABI: cpython-313-x86_64-linux-gnu
      Computed rustc target triple: x86_64-unknown-linux-gnu
      Installation directory: /work/home/.cache/puccinialin
      Downloading rustup-init from https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init
      Checking for Rust toolchain....
      Rust not found, installing into a temporary directory
      Traceback (most recent call last):
        ...
      httpx.ConnectError: [Errno -2] Name or service not known
      [end of output]
error: metadata-generation-failed

今の maturin は、Rust が無いと一時フォルダーに Rust を自動で入れようとします。手元の環境は外部への名前解決ができないため、その取得の段階で失敗しました。会社のネットワークやオフラインの CI で同じ文言が出たら、Rust が無いことが原因です。

直し方は C 拡張と同じ順番です。まず wheel のある版を選びます（手元で確かめた pydantic-core 2.50.4・tokenizers 0.23.3・cryptography 50.0.2 は、いずれも Linux x86_64 向けの wheel を持っていました）。どうしてもビルドするなら、Rust 公式の手順（rustup）で rustc と cargo を入れてから pip install をやり直します。

Microsoft Visual C++ 14.0 or greater is requiredとOS別のビルドツール

この節では、Windows で出る Microsoft Visual C++ 14.0 or greater is required の意味と、Windows・Mac・Linux でビルドツールを入れる方法が分かります。

この文言は、setuptools が Windows で C 拡張のコンパイラ（MSVC）を探して見つからなかったときに出します。手元の setuptools 84.2.1 のソース（setuptools/_distutils/compilers/C/msvc.py）には、次の文がそのまま書かれていました。

raise PlatformError(
    'Microsoft Visual C++ 14.0 or greater is required. '
    'Get it with "Microsoft C++ Build Tools": '
    'https://visualstudio.microsoft.com/visual-cpp-build-tools/'
)

Windows では手元で動かせないため、ここからは公式ドキュメントで確かめた範囲です。Python Wiki の WindowsCompilers によると、Python 3.5 以降の拡張は Visual C++ 14.x でビルドします。入れる前に、まず wheel のある版や Python の版を選べないかを確かめるのは、Linux と同じです。

Windows で Build Tools を入れたあとも失敗するときは、新しいターミナルを開き直してから pip を実行します。インストールの前から開いていたターミナルには、新しい環境変数が反映されないためです。

よくあるつまずき（buildフォルダーの残り・pipの取り違え）

この節では、直したつもりでも結果が変わらない、あるいは直していないのに通ってしまう、紛らわしい場面が分かります。

手元で驚いたのは、コンパイラを戻して一度ビルドに成功したあと、もう一度コンパイラを隠して同じフォルダーを入れ直すと、エラーにならずに入ってしまったことです。setuptools はソースのフォルダーに build/ を作り、コンパイル済みの .o・.so を残します。2回目はそれを使ったため、コンパイラが呼ばれませんでした。

$ find pkgs/cdemo/build -name '*.so' -o -name '*.o'
pkgs/cdemo/build/temp.linux-x86_64-cpython-313/src/cdemo.o
pkgs/cdemo/build/lib.linux-x86_64-cpython-313/cdemo.cpython-313-x86_64-linux-gnu.so
$ rm -rf pkgs/cdemo/build pkgs/cdemo/*.egg-info
$ pip install pkgs/cdemo
      error: [Errno 2] No such file or directory: 'x86_64-linux-gnu-gcc'
  ERROR: Failed building wheel for cdemo

No matching distribution found の直し方は、関連記事「pip No matching distribution foundの直し方」で扱っています。externally-managed-environment は、関連記事「externally-managed-environmentの直し方｜pip」で扱っています。インストールできたのに import で失敗するときは、関連記事「ModuleNotFoundErrorの原因と直し方｜No module named」を参照ください。

自分の環境で確かめるときは、次の2行が役に立ちます。

• 1ビルドせずに入るかを先に見るpip install --dry-run --only-binary=:all: 〇〇。失敗なら、その Python では wheel が無い
• 2使っている Python と pip の組を見るpython -m pip --version。パスと Python の版が、入れたい venv のものか
• 3呼ばれるコンパイラがあるかを見るpython -c 'import sysconfig; print(sysconfig.get_config_var("CC"))' の名前が PATH にあるか
• 4全文をファイルに残すpip install --log pip.log 〇〇 で、流れた原因の行を後から探せる

判断表：subprocess-exited-with-errorが出たらどこから確かめるか

この節では、状況ごとに最初の一手を選べる判断表と、手元で測った時間の比較が分かります。

よくある質問

この節では、subprocess-exited-with-error と Failed building wheel について、よく聞かれることへの答えが分かります。

Q. subprocess-exited-with-error は pip の不具合ですか。
多くの場合、違います。pip 自身が「This error originates from a subprocess, and is likely not a problem with pip.」と表示しているとおり、ビルドバックエンドの中で何かが足りないという意味です。原因は枠の中の最後の error の行に出ます。

Q. pip install --upgrade pip setuptools wheel で直りますか。
pip の版が原因（原因6）なら直ります。一方、ビルドは隔離された環境で行うため、venv の setuptools や wheel を上げても、ビルドの中で使われる版は変わりません。手元でも、コンパイラが無い・ヘッダーが無い・wheel が無いという原因は、これだけでは直りませんでした。

Q. Failed building wheel と出たあとに Successfully installed と出ました。
pip 23.0 までは、pyproject.toml を持たないパッケージで wheel のビルドに失敗すると、setup.py install で入れ直すことがありました。pip の変更履歴によると、この入れ直しは pip 23.1 で無くなり、今は wheel が作れなければ失敗で終わります。表示どおり入ったなら、import して動くかを確かめます。

Q. Visual Studio を丸ごと入れないといけませんか。
Microsoft は、IDE を含まない Build Tools for Visual Studio（MSVC のコンパイラ・ライブラリ・Windows SDK）を配布しています。Python Wiki の WindowsCompilers が、選ぶワークロードを載せています。その前に、wheel のある版や Python の版で避けられないかを確かめます。

Q. Python.h: No such file or directory はどうすれば直りますか。
Python のヘッダーが入っていません。Ubuntu・Debian は python3-dev、または使っている Python の版に合わせた python3.13-dev などを入れます。python3-config --includes で、どこのヘッダーを探しているかが分かります。

Q. Getting requirements to build wheel did not run successfully は何が原因ですか。
setup.py の実行の段階で失敗しています。手元では、ビルド依存の書き漏れ（No module named 'Cython'）と、pg_config が無い（psycopg2）の2つで、この段階の失敗を起こしました。枠の中の ModuleNotFoundError や Error: の行を見ます。

Q. --no-binary :all: を付けたら失敗するようになりました。
--no-binary は「wheel を使わずソースからビルドする」指定です。ふだんの開発では付けません。requirements.txt や pip.conf、環境変数 PIP_NO_BINARY に残っていないかも確かめます。

Q. Docker のビルドだけで失敗します。
python:3.x-slim などの軽いイメージにはコンパイラが入っていません。また、Alpine は musl を使うため、manylinux ではなく musllinux の wheel が要ります。wheel のある組み合わせを選ぶか、ビルド用のステージでだけ build-essential を入れます。

Q. conda や uv なら起きませんか。
conda はコンパイル済みのパッケージを配るので、同じパッケージでもビルドを避けられることがあります。uv も pip と同じく PyPI の wheel と sdist を使うため、合う wheel が無ければソースからのビルドになり、コンパイラなどが要る点は同じです。

Q. Mac の M1・M2 などで出ます。
arm64 向け（macosx_11_0_arm64 など）の wheel が無い版だと、ソースからのビルドになります。PyPI の Download files で arm64 の wheel がある版を探し、無ければ xcode-select --install で Command Line Tools を入れます。

まとめ

• error: subprocess-exited-with-error は、pip が起動したビルド用の子プロセスの失敗。原因は [N lines of output] の中の最後の error の行にある。
• 「×」の行の段階（build dependencies・requirements・metadata・Building wheel）で、疑う原因が変わる。
• 多いのは、自分の Python 向けの wheel が無くソースに回るケース。--only-binary=:all: で数秒で確かめ、wheel のある版か Python の版を選ぶ。
• pip が以前の版だと、PyPI に wheel があっても選べない。python -m pip install -U pip が最初の一手。
• ビルドが避けられないときは、文言どおりにコンパイラ・ヘッダー（-dev）・pg_config・Rust・MSVC を足す。ビルド依存の問題は requires と --build-constraint で直す。

参考・出典

確認日はいずれも 2026年11月6日です。

• pip documentation v26.3「pip install」（--only-binary・--prefer-binary・--no-binary・--no-build-isolation・--build-constraint）：https://pip.pypa.io/en/stable/cli/pip_install/
• pip documentation「Build System Interface」（ビルドの隔離・ビルド依存）：https://pip.pypa.io/en/stable/reference/build-system/
• Python Packaging User Guide「Glossary」（Wheel・Source Distribution・Build Backend）：https://packaging.python.org/en/latest/glossary/
• Python Wiki「WindowsCompilers」：https://wiki.python.org/python/platforms/WindowsCompilers.html
• Microsoft「Microsoft C++ Build Tools」：https://visualstudio.microsoft.com/visual-cpp-build-tools/
• Python Developer's Guide「Setup and building」（xcode-select・build-essential・dnf）：https://devguide.python.org/getting-started/setup-building/
• Psycopg「Installation」（psycopg2-binary・ビルドの前提）：https://www.psycopg.org/docs/install.html
• PyPI User Documentation「JSON API」：https://docs.pypi.org/api/json/
• pip documentation「Changelog」（23.1 の setup.py install の入れ直しの削除・25.3 の --build-constraint）：https://pip.pypa.io/en/stable/news/
• setuptools のソース（_distutils/compilers/C/msvc.py、手元の 84.2.1）

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。