Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Go: cgo: C compiler "gcc" not found in a minimal image

Why a project with no C fails on a C compiler, how to prove which package pulls cgo, and what changes when a library really needs it.

~5 min readGo
#Go#cgo#Docker#Cross Compilation
A Go build cube with an empty tool socket outlined in amber and a gear on a shelf beside it

Introduction & Quick Summary

Symptom. A Go project that builds on a laptop fails inside a small base image, and the compiler complains about a C compiler that the project never used directly:

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

Sometimes the trigger is go test rather than go build, sometimes it is go install with -trimpath, and sometimes it is a library like mattn/go-sqlite3 that genuinely needs C. On golang:alpine, the same Dockerfile that worked on Debian suddenly stops.

Cause. On Linux, cgo is enabled by default when a C toolchain exists at build time. Several standard-library packages pull in runtime/cgo on that basis, and any dependency using C does so deliberately. Alpine images ship musl and no compiler, so the # runtime/cgo step has nothing to run. The confusing part is that deleting cgo code does not remove the dependency on the toolchain: os/user, net and vet can all reach it.

Fix. Decide the two legitimate directions, and pick one on purpose:

dockerfile
# 1. no C at all: build static, run on scratch or distroless FROM golang:1.25-alpine AS build WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app FROM scratch COPY --from=build /out/app /app ENTRYPOINT ["/app"]
dockerfile
# 2. C required (sqlite, libvips, system libs): install the toolchain in the build stage FROM golang:1.25-alpine AS build RUN apk add --no-cache build-base pkgconfig WORKDIR /src COPY . . RUN CGO_ENABLED=1 go build -trimpath -o /out/app ./cmd/app

The rest of this guide covers which packages force cgo, how to keep a static binary with a C dependency, and the cross-compilation traps that produce the same message on a working machine.

Core Mechanics, Signatures & Reproducible Setup

CGO_ENABLED is a build setting, not a source property. When it is 1, the toolchain needs CC (default gcc), a linker, and for cgo packages, the headers of any C library they use. When it is 0, cgo-using packages either fall back to pure-Go implementations or fail to compile with build constraints exclude all Go files.

Reproduce the failure without Docker, by hiding the compiler from the toolchain:

bash
mkdir -p /tmp/cgoc && cd /tmp/cgoc go mod init example.com/cgoc >/dev/null cat > main.go <<'EOF' package main import ( "fmt" "os/user" ) func main() { u, err := user.Current() fmt.Println(u, err) } EOF go env CGO_ENABLED CC CC=/nonexistent/gcc go build ./... # cgo: C compiler "gcc" not found CGO_ENABLED=0 go build ./... # succeeds, uses the pure-Go resolver

The second build shows the important detail: the same source compiles without cgo, because net and os/user have pure-Go paths. A package that needs C has none, and its failure is a different message.

bash
# what the current environment claims go env CGO_ENABLED CC CXX GOOS GOARCH
bash
# what actually pulls cgo into the build graph go list -deps -f '{{if .CgoFiles}}{{.ImportPath}}{{end}}' ./... | sed '/^$/d'

That last command is the shortest way to answer "why is cgo involved at all": it lists every package in the dependency graph with at least one .c file.

Key Comparison Table

SituationCGO_ENABLEDResult
pure Go service, static binary0no libc dependency, runs on scratch
DNS via the system resolver1honours /etc/nsswitch.conf, glibc NSS
DNS without cgo0Go's own resolver, ignores NSS modules
mattn/go-sqlite31needs gcc, musl-dev or libc6-dev
modernc.org/sqlite0pure Go, larger binary
linking a .so at runtime1dynamic loader needed in the final image
cross-compiling for ARM0 or a cross CCtoolchain per target
go test on a machine without cc0avoids vet's cgo rebuild
Base imageHas gccHas libc headerscgo works out of the box
golang:1.25 (Debian)yesyesyes
golang:1.25-alpinenono (musl-dev missing)no
golang:1.25-alpine plus build-baseyesyesyes
gcr.io/distroless/staticnononot a build image
scratchnonoruntime only

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Alpine first, then the missing pieces

build-base is the meta-package: it pulls gcc, musl-dev, binutils and make in one step. Some libraries also need pkg-config and their own -dev package, and a missing header produces a fatal error: sqlite3.h: No such file or directory after cgo itself has been satisfied:

dockerfile
RUN apk add --no-cache build-base pkgconfig sqlite-dev
bash
# check a package's own instructions rather than guessing flags go doc github.com/mattn/go-sqlite3 | head -20

2. Static binaries that still need C

A cgo build links against libc, so copying it to scratch fails at startup with no such file or directory even though the file exists. The linker needs static archives:

dockerfile
RUN apk add --no-cache build-base RUN CGO_ENABLED=1 go build -trimpath \ -ldflags '-linkmode external -extldflags "-static"' \ -o /out/app ./cmd/app
bash
file /out/app # statically linked ldd /out/app # "not a dynamic executable"

This works cleanly with musl on Alpine. Static glibc binaries that use NSS (os/user, some DNS paths) print a warning at runtime and can fail on the user lookup, which is another reason to prefer a pure-Go path where possible.

3. Cross-compilation needs a cross compiler, not just a GOARCH

Setting GOARCH=arm64 with cgo enabled asks the host gcc to produce ARM objects, which fails with assembler errors rather than the "not found" message. Two working approaches:

# no C: cross-compile freely CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o app-arm64 ./cmd/app # C: install a cross compiler and point CC at it CGO_ENABLED=1 GOOS=linux GOARCH=arm64 CC=aarch64-linux-gnu-gcc go build -o app-arm64 ./cmd/app

In Docker, use --platform with buildx instead, so the compiler and the target match by construction.

4. go test and go vet rebuilding cgo packages

Older Go releases failed go test on Alpine even for pure-Go packages, because vet rebuilt runtime/cgo to collect facts. Modern releases avoid that when no C compiler is present, but a project pinned to an old toolchain still sees it:

bash
CGO_ENABLED=0 go test ./... # or, when cgo is genuinely needed go test -vet=off ./...

Turning vet off for the whole test run hides real problems, so prefer CGO_ENABLED=0 for CI unit tests and keep a separate cgo-enabled job for the packages that need it.

5. Runtime vs build: the loader and the libraries

A cgo binary built on Debian and run on Alpine fails with standard_init_linux.go: ... no such file or directory, which people read as a missing binary. It means the interpreter named in the ELF header (/lib64/ld-linux-x86-64.so.2) is absent:

bash
readelf -l /out/app | grep interpreter ldd /out/app # from the same base image as the final stage

The rule is simple: build and run on the same libc, or build static. Mixing glibc and musl across stages is the most common way to produce a binary that exists and will not start.

6. Making the decision explicit in the repository

Relying on the ambient environment means the build changes when someone installs a compiler. Pin the choice where the build runs:

# .github/workflows/ci.yml - name: Test env: CGO_ENABLED: "0" run: go test ./...
dockerfile
# or in the image, so every tool in the stage agrees ENV CGO_ENABLED=0

For the packages that truly need C, add a second job with CGO_ENABLED=1 and the toolchain installed, so the split is visible in CI rather than discovered in production.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Assuming CGO_ENABLED=0 is the default. It is not on Linux when a compiler is present.
  • Removing C code and expecting the toolchain requirement to disappear. net, os/user and vet can still reach cgo.
  • Installing gcc but not musl-dev. cgo finds the compiler and then fails on headers.
  • Copying a cgo binary into scratch. The dynamic loader is missing.
  • Cross-compiling with cgo and the host gcc. Use a cross compiler or buildx --platform.
  • Setting CGO_ENABLED only in the shell of one step. The next step reverts to the default.
  • Using -vet=off to silence a toolchain problem. It disables a real check.
  • Mixing glibc and musl base images across stages. The binary exists but cannot start.

Check the environment the build actually sees with the environment file inspector, verify file permissions when a copied binary refuses to execute with the chmod calculator, and compare the two Dockerfile variants with the text diff tool.

Reference: environment variables in cmd/go, cmd/cgo, and the Go wiki page on cgo.

Official references

primary documentation

The Go documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Go guides

More in Go

All Go guides

The guides filed next to this one in Go, in library order.