Python "subprocess-exited-with-error" build backend in CI

By Kaveh Alemi·Latchkey

This is the build backend's generic banner for "a build subprocess returned non-zero." The actual failure - a missing build module, a compiler error, or a bad config - is in the box-drawing output just above it.

What this error means

A build prints a boxed "x ... did not run successfully" section, then "error: subprocess-exited-with-error". The wrapper looks the same regardless of the underlying cause.

  x Getting requirements to build wheel did not run successfully.
  | exit code: 1
  +-> [6 lines of output]
      ModuleNotFoundError: No module named 'hatchling'
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: subprocess-exited-with-error

Common causes

A missing build backend or build dependency

The isolated build env lacks a module the backend imports (hatchling, setuptools-scm), so the subprocess fails.

A native compile failure inside the backend

A compiler or header error during the wheel build returns non-zero; pip only shows the wrapper.

How to fix it

Read the captured output, not the wrapper

1. Find the first concrete error: / ModuleNotFoundError: inside the box-drawing section.
2. Fix that specific line - add the build dep or system header it names.
3. Ignore the boilerplate "not a problem with pip" note.

Declare the build backend and its deps

Ensure [build-system] requires lists everything the backend imports.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

How to prevent it

• Declare a complete [build-system] requires.
• Prefer wheels in CI so the build backend never runs.
• Upgrade pip so build isolation provisions backends correctly.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation