Python "error: command 'gcc' failed with exit status 1" Variants

Unlike "gcc: not found", an exit status 1 means gcc ran and the compilation failed - a missing header, an incompatible flag, or a source error. The actual cause is the compiler message just above this line.

What this error means

A source build ends with error: command 'gcc' failed with exit status 1 (or x86_64-linux-gnu-gcc ... exit status 1). Above it is the real compiler error - a fatal error: for a missing header, an undeclared symbol, or a failed link.

  building 'sasl._sasl' extension
  sasl/sasl.c:21:10: fatal error: sasl/sasl.h: No such file or directory
   21 | #include <sasl/sasl.h>
      |          ^~~~~~~~~~~~~~
  compilation terminated.
  error: command 'gcc' failed with exit status 1

Common causes

A required library’s dev headers are missing

The extension needs a third-party library’s headers (here libsasl2). Without the -dev/-devel package, gcc cannot find the header and exits 1.

Toolchain or flag incompatibility

A newer/older gcc, a missing flag, or an incompatible source for your platform makes the compile fail even though gcc is installed.

How to fix it

Install the missing library dev package

Read the fatal error: header name, map it to a dev package, and install it.

# example: sasl/sasl.h -> libsasl2-dev
apt-get update && apt-get install -y build-essential libsasl2-dev python3-dev

Prefer a wheel to skip compiling

pip install --only-binary :all: <package>

Read the error above the wrapper

1. Find the first fatal error:/error: line above the gcc summary.
2. For a header, install the owning -dev package; for a symbol, check version compatibility.
3. Re-run after installing the missing piece.

How to prevent it

• Bake common dev headers into images that compile native deps.
• Prefer wheels and --only-binary in CI.
• Pin a Python/toolchain combination known to build your dependencies.

Related guides