Go cgo "gcc: command not found" - Fix Missing C Toolchain in CI

By Daniel Zoghalchali·Latchkey

A package uses cgo, so the Go build invoked the system C compiler - and there is no gcc/cc on the runner. cgo needs a working C toolchain that slim CI images often omit.

What this error means

A build fails with exec: "gcc": executable file not found in $PATH while compiling a cgo-enabled package. Pure-Go packages build fine; only the cgo one fails, and only on images without a compiler.

# runtime/cgo
exec: "gcc": executable file not found in $PATH

# or
cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in $PATH

Common causes

No C compiler on a slim runner image

Minimal/Alpine images skip a C toolchain. A package with cgo (sqlite drivers, some crypto, system bindings) cannot build without gcc/clang.

cgo unexpectedly enabled

A transitive dependency pulls in cgo even though your own code does not, so a build you assumed was pure Go now needs a compiler.

How to fix it

Install a C toolchain

# Debian/Ubuntu
apt-get update && apt-get install -y build-essential
# Alpine
apk add --no-cache build-base
go build ./...

Disable cgo if you do not need it

When no dependency truly requires cgo, a fully static pure-Go build avoids the compiler entirely.

CGO_ENABLED=0 go build ./...

Find what pulls in cgo

1. Build with go build -x to see the gcc invocation and which package triggers it.
2. If a driver offers a pure-Go variant (e.g. a non-cgo SQLite), switch to it.
3. Bake the C toolchain into the runner image if cgo is unavoidable.

How to prevent it

• Set CGO_ENABLED=0 for pure-Go builds to make them portable and toolchain-free.
• Bake build-essential/build-base into images that compile cgo packages.
• Prefer pure-Go driver variants where they exist.

Frequently asked questions

Related guides

References

• Go documentation
• GitHub Actions documentation