pip install error: subprocess-exited-with-error, exit code: 1 (tested)

error: subprocess-exited-with-error ... exit code: 1 means a package's build step failed, not pip. Read the last lines before [end of output]: below, a missing build dependency (No module named 'numpy') and a failed C compile (fatal error: ... No such file or directory), each reproduced and fixed.

1. What "exit code: 1" means

pip did not fail by itself: it ran a build step for a source package (an sdist or a local folder with setup.py/pyproject.toml) in a subprocess, and that subprocess exited with status 1. The real cause is printed inside the boxed output, usually the last line before [end of output]. The note says so: This error originates from a subprocess, and is likely not a problem with pip.

2. Case 1: setup.py imports something at build time

import numpy  # build-time import that is not declared anywhere
from setuptools import setup
setup(name="needs-numpy", version="0.1")

# A source package whose setup.py imports numpy at build time
python -m pip install ./a > log.txt 2>&1; echo "pip exit status: $?"
grep -E 'error|×|exit code|No module|note|ERROR' log.txt

Output (pip 26.2.2, Python 3.13.5; the grep keeps the important lines of a 40-line log):

pip exit status: 1
  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
      ModuleNotFoundError: No module named 'numpy'
  note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed to build 'file:///tmp/pc416/a' when getting requirements to build wheel

pip builds in an isolated environment that contains only the declared build requirements (here just setuptools), so numpy is missing even if it is installed in your venv. Fix: declare it as a build requirement:

# Fix for ./a: declare the build-time dependency in pyproject.toml
cat c/pyproject.toml
python -m pip install -q ./c > log3.txt 2>&1; echo "pip exit status: $?"
python -m pip list 2>/dev/null | grep -E 'needs-numpy'

[build-system]
requires = ["setuptools", "numpy"]
build-backend = "setuptools.build_meta"
pip exit status: 0
needs-numpy 0.1

If it is someone else's package, upgrade to a version that ships a wheel for your Python, or install the build dependency first and use pip install --no-build-isolation.

3. Case 2: a C extension fails to compile

from setuptools import setup, Extension
setup(name="fastthing", version="0.1",
      ext_modules=[Extension("fastthing", ["fast.c"])])

fast.c includes a header that is not installed (#include <missing_lib.h>):

# A source package with a C extension that needs a missing header
python -m pip install ./b 2>&1 | grep -E 'error|Error|fatal|exit code|note|hint|fail' ; echo "pip exit status: ${PIPESTATUS[0]}"

  Building wheel for fastthing (pyproject.toml): finished with status 'error'
  error: subprocess-exited-with-error
  │ exit code: 1
      fast.c:1:10: fatal error: missing_lib.h: No such file or directory
      error: Command '['x86_64-linux-gnu-gcc', '-fno-strict-overflow', '-Wsign-compare', '-DNDEBUG', '-g', '-O2', '-Wall', '-fPIC', '-I/tmp/ps416/ve/include', '-I/usr/include/python3.13', '-c', 'fast.c', '-o', 'build/temp.linux-x86_64-cpython-313/fast.o']' returned non-zero exit status 1.
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: failed-wheel-build-for-install
pip exit status: 1

The line to read is fatal error: missing_lib.h: No such file or directory: a system library's development headers are missing (on Debian/Ubuntu these are the -dev packages, e.g. libpq-dev for psycopg2), or there is no compiler at all. Usually the better fix is to avoid compiling: use a Python version the package publishes wheels for. See numpy metadata-generation-failed and scipy metadata-generation-failed for that case measured.

Related: pip install failed, pip install SyntaxError: invalid syntax.

Written with AI assistance. Measured on 2026-10-23 with pip 26.2.2, setuptools and gcc on Python 3.13.5 (Linux). The scripts ran verbatim and the output was pasted unedited. PlainTables is our extension; pip is free.