pip "error: command 'gcc' failed: No such file or directory" in CI
By Kaveh Alemi·Latchkey
A package needed to compile a C extension, but gcc is not on the runner. setuptools tried to spawn the compiler, the OS could not find the executable, and the build aborted.
What this error means
The wheel or install build fails with "error: command 'gcc' failed: No such file or directory" (or "'cc' failed"). The runner image lacks a C toolchain.
pip
building 'frozenlist._frozenlist' extension
error: command 'gcc' failed: No such file or directory
Diagnose it: is it the build backend or a missing system library?
Python packaging failures in CI split into build-backend configuration problems and missing system headers. The traceback usually points at the backend even when the real cause is an absent -dev package.
Terminal
python -m pip install --upgrade pip build
python -m build --wheel 2>&1 | tail -40
# a compiler error naming a .h file is a system dependency, not a Python one# e.g. "Python.h: No such file" -> python3-dev# "openssl/ssl.h" -> libssl-dev
Common causes
No build toolchain on the runner
Slim base images (alpine, slim Debian) ship without gcc, so any source compile fails immediately.
A source build was forced unnecessarily
A version pin or --no-binary made pip compile instead of using an available wheel, exposing the missing compiler.
How to fix it
Install a C toolchain before the build
Add the build-essential / gcc package for your base image.
If a binary wheel exists, install it and skip the compiler requirement.
Terminal
pip install --only-binary=:all: frozenlist
How to prevent it
Install build-essential in CI images that compile source packages.
Prefer binary wheels for compiled dependencies.
Pick a base image that already includes a toolchain when you build frequently.
Frequently asked questions
What causes pip "error: command 'gcc' failed: no such file or directory" in CI?
There are 2 common causes: no build toolchain on the runner and a source build was forced unnecessarily. Slim base images (alpine, slim Debian) ship without gcc, so any source compile fails immediately.
How do I fix pip "error: command 'gcc' failed: no such file or directory" in CI?
There are 2 fixes depending on which cause you have: install a c toolchain before the build and use a wheel instead of compiling. Work through them in order, since the first is the most common.
What does pip "error: command 'gcc' failed: no such file or directory" in CI actually mean?
The wheel or install build fails with "error: command 'gcc' failed: No such file or directory" (or "'cc' failed").
How do I stop pip "error: command 'gcc' failed: no such file or directory" in CI happening again?
Install build-essential in CI images that compile source packages. The prevention section lists 3 changes that keep it from recurring.
