GoReleaser cgo "gcc: not found" build error in CI

With CGO_ENABLED=1, go build needs a C compiler for the target platform. GoReleaser cross-compiles many targets, so a missing or wrong gcc for a target fails the build. Most Go binaries can build with CGO disabled instead.

What this error means

GoReleaser fails a target with "exec: \"gcc\": executable file not found in $PATH" or a cross-compiler like "aarch64-linux-gnu-gcc: not found".

  ⨯ build failed  error=failed to build for linux_arm64:
  exec: "aarch64-linux-gnu-gcc": executable file not found in $PATH
  exit status 1

Common causes

cgo is enabled without a cross toolchain

Cross-compiling with CGO_ENABLED=1 requires a target-specific C compiler that a standard runner does not have.

A dependency forces cgo

A package that links C code turns cgo on, so the build needs gcc even if your own code does not.

How to fix it

Disable cgo when you can

If nothing needs C linkage, set CGO_ENABLED=0 so builds are pure Go and cross-compile without a toolchain.

builds:
  - env:
      - CGO_ENABLED=0

Provide a cross toolchain when cgo is required

Install the target cross-compilers (or use a container image that has them) and point CC at them.

sudo apt-get update
sudo apt-get install -y gcc-aarch64-linux-gnu

How to prevent it

• Prefer CGO_ENABLED=0 for portable cross-compiled releases.
• Install cross toolchains only for targets that truly need cgo.
• Test the full target matrix with goreleaser build --snapshot.

Related guides