cgo: C compiler gcc not found Go Origin: Application & API Last updated 4 Nov 2026

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

A package using cgo needs a C compiler, but none is installed or CGO is disabled.

Exact message you may see cgo: C compiler "gcc" not foundexec: "gcc": executable file not found in $PATHcgo: exec gcc: executable file not foundBinary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub
Explore the map of this error Full error map →
Seen on: Go Docker Linux

Meaning

Install gcc (or build-essential / Xcode command line tools), or build without cgo with CGO_ENABLED=0 when pure-Go alternatives exist (e.g. modernc.org/sqlite instead of mattn/go-sqlite3). Minimal Docker images (alpine, scratch, golang:alpine) lack gcc by default.

Common causes

  • Alpine/minimal image without gcc
  • Cross-compiling with cgo-dependent packages
  • Xcode CLT missing on macOS
  • Windows without MinGW
  • CGO_ENABLED=0 but a package requires cgo

⚡ Quick fix

  1. apk add build-base / apt-get install -y build-essential / xcode-select --install
  2. Use a pure-Go library and CGO_ENABLED=0
  3. Cross-compile with a proper toolchain

Detailed fix by platform

Docker

  1. RUN apk add --no-cache build-base in the build stage, copy the binary into a slim stage

How to diagnose

  1. Package — Needs cgo?
  2. Image — gcc present?
  3. Alternative — Pure Go?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Application & API. Errors that are often confused with or caused by this one (click to open):

assignment mismatch: 1 variable but f returns 2 values — Go: assignment mismatch: 1 variable but os.Open returns 2 values (Go)assignment mismatch: …cannot assign to struct field m[k].f in map — Go: cannot assign to struct field users["bob"].Age in map (Go)cannot assign to stru…COPY failed — COPY failed: file not found in build context / "/app/x": not found (Docker)COPY faileddid not complete successfully — failed to solve: process "/bin/sh -c ..." did not complete successfully: exit code: 1 (Docker)did not complete succ…exec format error — exec /usr/local/bin/docker-entrypoint.sh: exec format error (Docker)exec format errorfailed to read dockerfile — failed to solve: failed to read dockerfile: open Dockerfile: no such file or directory (Docker)failed to read docker…forbidden path outside the build context — COPY failed: forbidden path outside the build context: ../file (Docker)forbidden path outsid…function main is undeclared in the main package — Go: runtime.main_main·f: function main is undeclared in the main package (Go)function main is unde…cgo: C co…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.