Python "error: command 'gcc' failed" - Missing Compiler in CI

pip tried to compile a C extension but there is no working C compiler on the runner. The gcc (or cc) binary is missing, so the build cannot start.

What this error means

A source build fails with error: command gcc failed: No such file or directory or unable to execute gcc. The compiler itself is absent - distinct from a header-not-found error, where gcc runs but can’t find a file.

error: command 'gcc' failed: No such file or directory
# or
unable to execute 'gcc': No such file or directory
error: command 'gcc' failed with exit status 1

Common causes

No C toolchain on a slim image

Slim/Alpine base images omit a compiler to stay small. Any package without a prebuilt wheel then fails to build because gcc is not installed.

Toolchain present but incomplete

make/headers may exist while the actual compiler or cc symlink is missing, so the build still can’t invoke gcc.

How to fix it

Install the build toolchain

# Debian/Ubuntu
apt-get update && apt-get install -y build-essential
# Alpine
apk add --no-cache build-base
# RHEL/Fedora
dnf groupinstall -y "Development Tools"

Avoid the build with a wheel

If the package ships a wheel for your platform, install it and no compiler is needed.

pip install --prefer-binary -r requirements.txt

How to prevent it

• Bake build-essential/build-base into images that compile native deps.
• Prefer wheels and --prefer-binary in CI.
• Use full base images (not slim/Alpine) when native builds are unavoidable.

Related guides