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.

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:
# runtime/cgo
cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in $PATHSometimes 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:
# 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 /out/app /app
ENTRYPOINT ["/app"]# 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/appThe 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:
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 resolverThe 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.
# what the current environment claims
go env CGO_ENABLED CC CXX GOOS GOARCH# 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
| Situation | CGO_ENABLED | Result |
|---|---|---|
| pure Go service, static binary | 0 | no libc dependency, runs on scratch |
| DNS via the system resolver | 1 | honours /etc/nsswitch.conf, glibc NSS |
| DNS without cgo | 0 | Go's own resolver, ignores NSS modules |
mattn/go-sqlite3 | 1 | needs gcc, musl-dev or libc6-dev |
modernc.org/sqlite | 0 | pure Go, larger binary |
linking a .so at runtime | 1 | dynamic loader needed in the final image |
| cross-compiling for ARM | 0 or a cross CC | toolchain per target |
go test on a machine without cc | 0 | avoids vet's cgo rebuild |
| Base image | Has gcc | Has libc headers | cgo works out of the box |
|---|---|---|---|
golang:1.25 (Debian) | yes | yes | yes |
golang:1.25-alpine | no | no (musl-dev missing) | no |
golang:1.25-alpine plus build-base | yes | yes | yes |
gcr.io/distroless/static | no | no | not a build image |
scratch | no | no | runtime 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:
RUN apk add --no-cache build-base pkgconfig sqlite-dev# check a package's own instructions rather than guessing flags
go doc github.com/mattn/go-sqlite3 | head -202. 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:
RUN apk add --no-cache build-base
RUN CGO_ENABLED=1 go build -trimpath \
-ldflags '-linkmode external -extldflags "-static"' \
-o /out/app ./cmd/appfile /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/appIn 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:
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:
readelf -l /out/app | grep interpreter
ldd /out/app # from the same base image as the final stageThe 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 ./...# or in the image, so every tool in the stage agrees
ENV CGO_ENABLED=0For 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=0is the default. It is not on Linux when a compiler is present. - Removing C code and expecting the toolchain requirement to disappear.
net,os/userand vet can still reach cgo. - Installing
gccbut notmusl-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 orbuildx --platform. - Setting
CGO_ENABLEDonly in the shell of one step. The next step reverts to the default. - Using
-vet=offto 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 documentationThe Go documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Go work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Go guides
All Go guidesGo: cannot find main module and where go.mod is looked up
The go command searched upward and found no module. Create it at the right level, join modules with go.work, and check GOMOD before guessing.
Go: build constraints exclude all Go files in a package
The package vanished for this platform, not the code. Read the ignored file list, then rename a suffix or pass the tag.
Go 1.26: go fix rewrites, errors.AsType and go.mod surprises
go fix now modernizes code, errors.AsType compiles instead of panicking, and go mod init writes the previous minor on purpose.
Go: panic: assignment to entry in nil map
Reads on a nil map are legal, writes panic. Initialise in a constructor, allocate inner maps, and do not confuse this with a concurrent write.
More in Go
All Go guidesThe guides filed next to this one in Go, in library order.